Style Dictionary: transformando e gerando tokens

O Style Dictionary (criado pela Amazon) é uma ferramenta de compilação que recebe definições de tokens de projeto em formato JSON e as gera em qualquer formato de destino: propriedades personalizadas CSS, módulos ES JavaScript, variáveis Sass, constantes Swift para iOS, recursos XML para Android e qualquer formato personalizado que seja definido. Uma única fonte de verdade, muitas saídas.

Instale com npm install --save-dev style-dictionary. Inicialize uma estrutura de projeto com npx style-dictionary init; esse comando cria um config.json (ou config.js) e um diretório tokens/. A configuração informa ao Style Dictionary onde encontrar os arquivos de tokens e onde gravar as saídas.

O Style Dictionary usa uma estrutura JSON aninhada em que os nós folha têm uma propriedade value. Por exemplo: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. O caminho até o valor (cor, primário, 500) torna-se o nome do token após a transformação, geralmente formatado como color-primary-500 ou --color-primary-500.

Execute npx style-dictionary build --config config.json (ou style-dictionary build, se estiver configurado nos scripts de package.json). O Style Dictionary lê todos os arquivos de tokens da origem configurada, aplica as transformações e grava as saídas nos destinos configurados. Os erros no formato dos tokens são informados com o nome e o caminho do arquivo.

O config.json define plataformas: css (gera um arquivo CSS com propriedades personalizadas), js (gera um objeto JS) e scss (gera variáveis Sass). Cada plataforma especifica o diretório de saída, o nome do arquivo, o formato (o modelo) e as transformações (as funções de processamento do nome e do valor) que devem ser aplicadas.

O Style Dictionary inclui transformações integradas: name/cti/kebab converte o caminho aninhado em color-primary-500, name/cti/camel produz colorPrimary500, size/rem converte valores em pixels para rem e color/hex normaliza as cores para hexadecimal. As transformações podem ser combinadas e são aplicadas em ordem.

É possível registrar transformações personalizadas com StyleDictionary.registerTransform(). Por exemplo, uma transformação que converta valores em pixels para pontos do iOS ou outra que adicione um prefixo específico da empresa a todos os nomes de tokens. As transformações personalizadas oferecem controle total sobre como os valores são processados antes da saída.

Os formatos personalizados definem o modelo do arquivo de saída. StyleDictionary.registerFormat() recebe o dicionário de tokens transformados e retorna uma cadeia de caracteres — o conteúdo do arquivo. É possível gerar tokens como tipos TypeScript, como um objeto de tema do React, como uma extensão de configuração do Tailwind ou em qualquer outro formato exigido pela sua pilha.

Após a compilação, importe a saída CSS na sua folha de estilos global: @import './tokens/tokens.css'. Importe a saída JS nos componentes ou na configuração do Tailwind: import tokens from './tokens/tokens.js'. O CSS fornece propriedades personalizadas para tematização em tempo de execução; o JS fornece constantes tipadas para o Tailwind e para a lógica JavaScript.

O Style Dictionary oferece suporte a referências de tokens usando chaves: { "value": "{color.primary.500}" }. Isso cria equivalências semânticas entre tokens — o token semântico referencia um token primitivo. Durante a compilação, o Style Dictionary resolve as referências e gera o valor final resolvido (ou uma referência a uma variável CSS, dependendo do formato).

Execute o Style Dictionary como um script prebuild do npm para que os tokens sejam sempre regenerados antes da compilação da aplicação. Adicione "prebuild": "style-dictionary build" ao package.json. Isso garante que qualquer alteração nos arquivos JSON dos tokens seja refletida nas saídas CSS e JS antes que a compilação do React as processe.

Qual é a finalidade das transformações no Style Dictionary?

O Style Dictionary converte o JSON dos tokens em qualquer formato de saída: variáveis CSS, módulos JS, Sass, iOS e Android. O JSON dos tokens usa objetos aninhados com nós folha que têm a propriedade value. As transformações processam nomes e valores (camelCase, px-to-rem); os formatos definem o modelo de saída. As referências de tokens ({color.primary.500}) permitem criar equivalências semânticas. Automatize com um script prebuild para que os tokens estejam sempre atualizados antes da compilação do React.