Style Dictionary: trasformazione e generazione dei token

Style Dictionary, creato da Amazon, è uno strumento di build che prende le definizioni dei design token in formato JSON e le converte in qualsiasi formato di destinazione: proprietà personalizzate CSS, moduli JavaScript ES, variabili Sass, costanti Swift per iOS, risorse XML per Android e qualsiasi formato personalizzato definito. Un'unica fonte di verità, molteplici output.

Installare con npm install --save-dev style-dictionary. Inizializzare la struttura del progetto con npx style-dictionary init, che crea un config.json (o config.js) e una directory tokens/. La configurazione indica a Style Dictionary dove trovare i file dei token e dove scrivere gli output.

Style Dictionary usa una struttura JSON annidata in cui i nodi foglia hanno una proprietà value. Per esempio: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Il percorso che conduce al valore (color, primary, 500) diventa il nome del token dopo la trasformazione, in genere formattato come color-primary-500 o --color-primary-500.

Eseguire npx style-dictionary build --config config.json (oppure style-dictionary build se configurato negli script di package.json). Style Dictionary legge tutti i file dei token dalla sorgente configurata, applica le trasformazioni e scrive gli output nelle destinazioni configurate. Gli errori nel formato dei token vengono segnalati indicando il nome e il percorso del file.

Il file config.json definisce le piattaforme: css (produce un file CSS con proprietà personalizzate), js (produce un oggetto JS), scss (produce variabili Sass). Ogni piattaforma specifica la directory di output, il nome del file, il formato (il modello) e le trasformazioni (le funzioni che elaborano nome e valore) da applicare.

Style Dictionary include trasformazioni integrate: name/cti/kebab converte il percorso annidato in color-primary-500, name/cti/camel produce colorPrimary500, size/rem converte i valori in pixel in rem, color/hex normalizza i colori nel formato esadecimale. Le trasformazioni sono componibili e vengono applicate in ordine.

È possibile registrare trasformazioni personalizzate con StyleDictionary.registerTransform(). Per esempio, una trasformazione che converte i valori in pixel in punti iOS o una che aggiunge un prefisso specifico dell'azienda a tutti i nomi dei token. Le trasformazioni personalizzate offrono il pieno controllo sull'elaborazione dei valori prima dell'output.

I formati personalizzati definiscono il modello del file di output. StyleDictionary.registerFormat() riceve il dizionario dei token trasformati e restituisce una stringa, ovvero il contenuto del file. È possibile produrre token come tipi TypeScript, come oggetto di tema React, come estensione di una configurazione Tailwind o in qualsiasi altro formato richiesto dallo stack.

Dopo la build, importare l'output CSS nel foglio di stile globale: @import './tokens/tokens.css'. Importare l'output JS nei componenti o nella configurazione Tailwind: import tokens from './tokens/tokens.js'. Il CSS fornisce proprietà personalizzate per la gestione dei temi a runtime; il JS fornisce costanti tipizzate per Tailwind e per la logica JavaScript.

Style Dictionary supporta i riferimenti ai token usando le parentesi graffe: { "value": "{color.primary.500}" }. In questo modo si creano alias per i token semantici: il token semantico fa riferimento a un token primitivo. Durante la build, Style Dictionary risolve i riferimenti e produce il valore finale risolto (oppure un riferimento a una variabile CSS, a seconda del formato).

Eseguire Style Dictionary come script npm prebuild, in modo che i token vengano sempre rigenerati prima della build dell'applicazione. Aggiungere "prebuild": "style-dictionary build" a package.json. In questo modo ogni modifica ai file JSON dei token viene riflessa negli output CSS e JS prima che la build React li elabori.

Style Dictionary converte il JSON dei token in qualsiasi formato di output: variabili CSS, moduli JS, Sass, iOS e Android. Il JSON dei token usa oggetti annidati con nodi foglia value. Le trasformazioni elaborano nomi e valori (camelCase, da px a rem); i formati definiscono il modello di output. I riferimenti ai token ({color.primary.500}) consentono di creare alias semantici. Automatizzare il processo con uno script prebuild mantiene i token aggiornati prima della build React.