Tokens no Tailwind, variáveis CSS e CSS-in-JS

A saída da plataforma CSS do Style Dictionary gera um arquivo de propriedades personalizadas do CSS: --color-primary-500: #3b82f6; --spacing-4: 16px; e assim por diante. Essas variáveis são definidas em :root, tornando-as disponíveis globalmente. Essa é a base para o uso de todos os tokens na aplicação.

Importe o arquivo de tokens CSS gerado na sua folha de estilos global ou no componente de layout raiz: @import './tokens/tokens.css'. No Next.js, importe-o em app/layout.tsx ou styles/globals.css. Depois de importado, toda regra CSS e todo componente da aplicação poderão fazer referência às propriedades personalizadas.

Faça referência às variáveis CSS nas folhas de estilos dos componentes ou nos Módulos CSS: background-color: var(--color-primary-500); e padding: var(--spacing-4);. Se o valor do token mudar na fonte JSON, recompilar o Style Dictionary atualizará o arquivo CSS, e todos os componentes que usam essa variável refletirão automaticamente o novo valor.

As propriedades personalizadas do CSS permitem alternar o tema em tempo de execução. No modo escuro, substitua os valores dos tokens sob um seletor de tema: [data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }. Definir document.documentElement.setAttribute('data-theme', 'dark') alterna instantaneamente todos os valores dos tokens, sem recarregar nem recompilar.

Estenda o tema do Tailwind em tailwind.config.js para usar valores dos tokens: theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }. Importe a saída JS do Style Dictionary na configuração do Tailwind para garantir que as classes do Tailwind (bg-primary-500) sempre usem os valores oficiais dos tokens.

Para temas alternáveis em tempo de execução no Tailwind, configure a cor para fazer referência a uma variável CSS: 'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'. Isso exige que sua variável CSS armazene os componentes RGB sem o invólucro rgb() (--color-primary-rgb: 59 130 246). O Tailwind então gerencia automaticamente os utilitários de opacidade.

As bibliotecas de CSS em JavaScript usam um objeto de tema JavaScript. Passe a saída JS do Style Dictionary como o valor do provedor de tema: <ThemeProvider theme={tokens}>. Os componentes acessam os tokens por meio de const theme = useTheme() e theme.color.primary[500]. O Style Dictionary gera o objeto de tokens tipado; o provedor de tema o distribui.

O plug-in stylelint-no-hardcoded-colors e regras personalizadas do ESLint podem impor que nenhum valor hexadecimal codificado diretamente apareça em folhas de estilos ou arquivos de componentes. Se um desenvolvedor escrever color: #3b82f6 em vez de color: var(--color-primary-500), o verificador sinalizará o problema. Isso mantém o sistema de tokens como a única fonte de cores.

Quando os nomes das classes do Tailwind são construídos dinamicamente a partir dos nomes dos tokens em tempo de execução, a limpeza do Tailwind pode remover essas classes, porque elas não aparecem como strings estáticas no código-fonte. Adicione padrões de classes dinâmicas à safelist em tailwind.config.js: safelist: [{ pattern: /bg-primary-/ }].

O plug-in Figma Tokens exporta diretamente os valores dos tokens do Figma para o formato JSON do Style Dictionary. O fluxo de trabalho é o seguinte: profissionais de design atualizam as cores nas Variáveis do Figma, exportam por meio do plug-in, registram o JSON atualizado no controle de versão, o script de pré-compilação executa o Style Dictionary e as saídas CSS e JS atualizadas são usadas na aplicação React. O design e o código permanecem sincronizados.

As propriedades personalizadas do CSS têm escopo definido para o elemento em que são definidas e para seus descendentes. Isso permite substituições de tema no nível do componente: um componente de cartão pode definir --color-background: var(--color-surface-elevated) no seu elemento raiz, e todos os descendentes usarão a cor de superfície elevada sem encaminhamento de propriedades.

Qual é a principal vantagem de usar propriedades personalizadas do CSS (variáveis) para tokens de design em vez de valores estáticos do Tailwind?

O Style Dictionary fornece propriedades personalizadas do CSS para importação global e objetos JS para integração com Tailwind e CSS em JavaScript. As variáveis CSS permitem alternar o tema em tempo de execução por meio de substituições [data-theme]. O Tailwind estende sua configuração com valores de tokens provenientes da saída JS; para uma tematização compatível com opacidade, configure o Tailwind para fazer referência a variáveis CSS RGB. As regras de verificação impõem o uso exclusivo de cores provenientes dos tokens, mantendo valores codificados diretamente fora da base de código.