Como escalar design tokens sem o sistema desabar

O problema de escala

Um sistema de design tokens que funciona com 50 tokens costuma começar a quebrar quando chega a 500. Segundo o autor, a causa geralmente é governança: ninguém decidiu cedo quem é dono das mudanças, como renomeações se propagam ou o que acontece quando duas equipes precisam de mudanças conflitantes na mesma primitiva no mesmo sprint. A estrutura precisa existir antes que a escala force a questão.

Nomes intuitivos do primeiro dia, como blue-500 ou btn-bg, funcionam até a contagem passar de algumas centenas - quando deixa de ficar claro pelo nome se algo é primitiva, alias semântico ou override específico de componente.

Separar primitivas de semântica

O autor relata sistemas em que todo token semântico era apenas uma primitiva com nome mais amigável: color.text.primary com o mesmo valor hexadecimal fixo de color.gray.900, sem alias nem referência. O problema aparece quando alguém precisa de um tema escuro: como não há referência para redirecionar, cada componente precisa ser encontrado e editado manualmente.

A correção é simples: primitivas guardam valores brutos, tokens semânticos guardam referências, e componentes consomem apenas semântica. Assim, trocar de tema vira uma questão de redirecionar aliases, não de buscar códigos hexadecimais em todos os componentes. Uma regra de linter pode reforçar isso, sinalizando qualquer token semântico cujo valor seja literal em vez de referência - e um prefixo adequado permite ao linter rejeitar componentes que acessam primitivas diretamente.

Versionar tokens como uma API

Um pacote de tokens sem histórico de versões é um pacote que todos têm medo de mexer. O autor recomenda tratar mudanças que quebram compatibilidade - renomear um token, alterar uma referência semântica, remover uma primitiva descontinuada - como uma mudança de API: bump de versão maior, entrada em changelog e janela de descontinuação em que o nome antigo ainda resolve, mas se sinaliza.

Um arquivo gerado de tokens descontinuados pode mapear o nome antigo ao substituto e à versão de remoção; uma checagem em tempo de build resolve o nome antigo para o novo valor e imprime um aviso no console. Isso só funciona se alguém for dono da decisão de subir a versão maior: renomear no lugar, sem bump nem janela de descontinuação, transforma uma mudança pequena em incidente para todas as equipes que consomem o pacote.

Automatizar propagação, não revisão

A tentativa em escala é adicionar mais revisão manual, o que não escala - apenas transfere o gargalo do código para as pessoas. O que escala é um pipeline de build que gera todas as saídas por plataforma (variáveis CSS, assets iOS, XML Android) a partir da mesma fonte de verdade, a cada merge. Colocar isso em CI e falhar o build se qualquer saída estiver desatualizada é como se sabe que a mudança alcançou todas as plataformas.

Antes de publicar, o autor sugere um teste de contraste que sinalize qualquer par semântico de cores (texto/fundo) abaixo do WCAG AA, já que mudanças de token podem quebrar acessibilidade silenciosamente em todas as telas. Revisores devem focar no diff do código-fonte dos tokens e nos resultados das checagens, não em confirmar manualmente que iOS e web estão sincronizados.