Arquitetura de tokens para múltiplos temas e marcas

Um tema altera o modo de cor da mesma marca (versões clara e escura do mesmo produto). Uma marca é uma identidade visual diferente — os mesmos componentes do sistema de projeto são renderizados com cores, tipografia e espaçamento diferentes para atender a produtos ou clientes distintos. Ambos usam a mesma arquitetura de tokens, mas em níveis de abstração diferentes.

Os tokens primitivos são a paleta completa de valores brutos disponíveis para o sistema. Eles incluem cada variação de cor (color-blue-50 a color-blue-900), cada unidade de espaçamento e cada tamanho de fonte. Os tokens primitivos nunca são usados diretamente nos componentes — eles são apenas referenciados pelos tokens semânticos. A paleta é definida uma vez e compartilhada entre todos os temas e marcas.

Os tokens semânticos expressam uma intenção: color-background-page, color-text-primary, color-action-primary. Cada token semântico referencia um valor de token primitivo apropriado para o tema atual. Os componentes são criados exclusivamente com base nos tokens semânticos. É nesta camada que ocorre a tematização.

No tema claro: color-background-page referencia color-white, color-text-primary referencia color-gray-900 e color-action-primary referencia color-blue-500. Esses mapeamentos são definidos em um arquivo de tokens específico do tema que substitui a camada semântica no contexto claro.

No tema escuro: color-background-page referencia color-gray-950, color-text-primary referencia color-gray-50 e color-action-primary referencia color-blue-400 (um pouco mais claro para oferecer contraste em fundos escuros). Apenas os mapeamentos semânticos mudam — a paleta primitiva e todos os componentes permanecem inalterados.

A marca A usa azul como cor primária (color-action-primary: {color-blue-500}). A marca B usa verde (color-action-primary: {color-green-500}). O componente de botão lê var(--color-action-primary) — ele não tem qualquer conhecimento de qual marca está ativa. As substituições de marca alteram apenas os mapeamentos dos tokens semânticos, nunca o código dos componentes.

As propriedades personalizadas CSS tornam trivial a troca de tema em tempo de execução. Armazene o tema atual em um atributo de dados: document.documentElement.setAttribute('data-theme', 'dark'). As regras CSS substituem os tokens semânticos sob [data-theme="dark"]. O navegador resolve imediatamente todas as referências var() para os novos valores — não é necessário renderizar novamente com JavaScript.

Para marcas diferentes atendidas por implantações separadas, use a tematização em tempo de compilação: gere arquivos CSS de tokens separados por marca com o Style Dictionary e carregue o CSS da marca correta na inicialização da aplicação. Essa abordagem é adequada quando a marca é determinada no momento da implantação (domínios, subdomínios ou instâncias white label diferentes), não durante a interação do usuário.

Um sistema com várias marcas e vários temas exige uma matriz bidimensional: Marca A clara, Marca A escura, Marca B clara e Marca B escura. As propriedades personalizadas CSS lidam elegantemente com isso por meio de seletores aninhados: [data-brand="a"][data-theme="dark"] substitui os tokens semânticos para essa combinação específica. Quatro combinações são quatro blocos CSS, não quatro bases de código.

À medida que o sistema de projeto evolui, tokens são adicionados, renomeados ou removidos. Mantenha os tokens sob controle de versão no mesmo repositório do código. Ao descontinuar um token, mantenha o nome antigo como uma referência alternativa que aponta para o novo nome durante um ciclo de lançamento, adicione um comentário de descontinuação e atualize o código consumidor. Coordene as alterações nos tokens entre projeto e engenharia por meio de um registro de alterações estruturado.

A governança define quem pode adicionar ou alterar tokens e qual processo de revisão é necessário. Tokens primitivos exigem a aprovação da equipe de projeto. Tokens semânticos exigem revisão das equipes de projeto e engenharia. Tokens de componentes podem ser gerenciados pelo responsável pelo componente. Sem essa governança, surgem tokens duplicados e a garantia de uma "fonte única da verdade" se enfraquece.

Por que os componentes devem fazer referência a tokens semânticos em vez de tokens primitivos?

Os temas alteram os modos de cor dentro de uma marca; as marcas são identidades visuais diferentes. Os tokens primitivos são a paleta bruta; os tokens semânticos expressam significado e permitem a aplicação de temas. Os componentes usam apenas tokens semânticos. O modo escuro e as substituições de marca alteram apenas os mapeamentos dos tokens semânticos — os componentes permanecem inalterados. A aplicação de temas em tempo de execução usa propriedades personalizadas do CSS com seletores [data-theme]; a definição da marca em tempo de compilação gera um CSS separado para cada marca. A governança e o versionamento dos tokens mantêm o sistema consistente à medida que ele evolui.