Implementando temas para várias marcas com variáveis CSS

A tematização para várias marcas mapeia um único conjunto de tokens de alias de componentes para diferentes valores de tokens globais por marca. Os componentes referenciam tokens de alias; os arquivos de tema da marca remapeiam os aliases para globais específicos da marca.

Defina os tokens globais em :root: todos os valores brutos de cor, espaçamento e tipografia. Essa é a marca padrão. Os componentes nunca referenciam os globais diretamente — sempre por meio de aliases.

Os tokens de alias referenciam os globais usando var(): --color-action: var(--color-brand-primary). Os componentes usam --color-action. Alterar o significado de --color-brand-primary modifica todo o sistema.

Aplique temas de marca com uma classe em html ou em um elemento contêiner. Cada classe de tema substitui os tokens globais no escopo daquela marca. Os componentes dentro do contêiner herdam automaticamente os valores da marca.

O modo escuro é uma variante de tema — uma classe ou consulta de mídia que substitui os tokens de cor. Use prefers-color-scheme para o padrão do OS e uma classe .dark para a substituição escolhida pelo usuário. Ambos alteram os mesmos tokens de alias.

As propriedades personalizadas do CSS entram em cascata e são herdadas. Um tema aplicado a um elemento contêiner afeta todos os seus descendentes. Temas aninhados substituem os temas externos no nível do contêiner — algo útil em cenários de tematização de widgets dentro de páginas.

Garanta que os tokens de alias estejam sempre definidos. Se uma classe de tema estiver ausente, o alias deverá usar um valor padrão de forma adequada. Use a sintaxe de valor alternativo de var() do CSS: var(--color-action, #3b82f6) para evitar texto invisível ou fundos ausentes.

O Style Dictionary pode gerar arquivos CSS de tema separados a partir de um JSON de tokens. A etapa de compilação gera theme-brand-a.css e theme-brand-b.css. Carregue o arquivo apropriado em tempo de execução ou compile-o em pacotes separados por marca.

Escreva testes de regressão visual que renderizem cada componente em cada tema. Percy e Chromatic capturam telas para cada variante de tema. Os testes visuais automatizados detectam regressões quando os valores dos tokens globais mudam inesperadamente.

Alterne classes de tema com JavaScript: document.documentElement.classList.replace("theme-a", "theme-b"). As variáveis CSS são atualizadas instantaneamente sem renderizar novamente os componentes — não é necessária uma nova renderização do React nem o recálculo de estilos de valores estáticos.

As variáveis CSS são resolvidas no momento da pintura — alterar uma variável raiz dispara a repintura de todos os elementos que a utilizam. Limite as alterações de variáveis globais às interações do usuário, como a alternância de tema, em vez de usá-las em ciclos de animação. Use transições de propriedades individuais para efeitos de tematização animados.

Como os temas baseados em propriedades personalizadas do CSS permitem alternar entre marcas sem alterar o CSS dos componentes?

A tematização para várias marcas separa os valores brutos dos tokens globais dos tokens de alias semânticos. As classes de tema substituem os globais no escopo de um contêiner. Os componentes que referenciam aliases refletem automaticamente o tema de marca ativo, permitindo a alternância em tempo de execução sem alterações no código dos componentes.