TOKENS QUE SOBREVIVEM
Construa um sistema de design tokens que sobreviva ao próximo refresh visual. Estrutura de três camadas, nomenclatura semântica, padrões do mundo real.
Por que a maioria dos sistemas de tokens não sobrevive a redesigns
A maioria dos sistemas de design tokens é descontinuada em até dois anos porque codificavam os valores visuais do momento em vez da intenção semântica por trás deles. Um token chamado blue-500 fica preso a um valor azul para sempre; um token chamado accent-primary sobrevive a qualquer mudança de cor porque o próximo designer o mapeia para qualquer equivalente azul que o novo sistema usa.
A regra única que separa sistemas de tokens que sobrevivem dos que morrem: nomeie tokens pelo propósito, não pela aparência. accent-primary, surface-base, text-secondary, danger-bg. Nunca blue-500, gray-900, red-light. O nome semântico é o contrato; o valor é o detalhe de implementação.
A arquitetura de três camadas
Camada 1: primitivos. Valores brutos de cor, espaçamento, tipografia. blue-50, blue-100, blue-200..., blue-900. space-1, space-2..., space-12. Esses existem como a escala subjacente e raramente mudam.
Camada 2: semântica. Tokens nomeados por propósito que mapeiam para primitivos. accent-primary mapeia para blue-500, accent-hover mapeia para blue-600, surface-base mapeia para gray-50, text-primary mapeia para gray-900. Componentes referenciam estes, nunca os primitivos diretamente.
Camada 3: escopo de componente. Tokens por componente que mapeiam para os semânticos. button-primary-bg mapeia para accent-primary, card-border mapeia para border-subtle, nav-active-bg mapeia para accent-emphasis. Componentes consomem estes.
Quando a reformulação da marca acontece, você altera a escala primitiva e possivelmente o mapeamento semântico-para-primitivo. Tokens de escopo de componente fluem inalterados. O redesign é entregue em dias em vez de meses.
O que codificar e o que deixar hard-coded
Codificar: cor, espaçamento, tipografia (famílias de fonte, tamanhos, pesos, alturas de linha), border-radius, sombra, duração de movimento e easing, larguras de breakpoint.
Não codificar: valores específicos de layout (max-width de 1280 no template do artigo), offsets de posicionamento pontuais, coreografia de animação que é única para um único componente. Estes pertencem inline; codificá-los cria um sistema que luta contra si mesmo.
O teste de decisão: outro componente plausivelmente usaria este mesmo valor? Se sim, codifique. Se não, deixe hard-coded.
Implementação na stack
Propriedades customizadas de CSS no limite dos tokens. Defina os primitivos e semânticos em :root, sobrescreva em [data-theme="dark"]. Componentes referenciam os tokens semânticos, nunca os primitivos.
Tokens acessíveis por JS via um arquivo TypeScript gerado da mesma fonte. Ferramentas como Style Dictionary, Theo, ou um gerador customizado pequeno produzem ambas as variáveis CSS e exportações TS de uma única fonte JSON ou YAML. A fonte única significa que animações JS e styled components permanecem em sincronismo com stylesheets.
Documente o sistema em uma única página (uma página do Storybook ou uma página /design no próprio site) para que futuros contribuidores a encontrem. Sistemas de tokens que não são descobríveis são contornados em poucos meses por pessoas que não sabem que existem.