Style Dictionary : transformer et générer des jetons

Style Dictionary, créé par Amazon, est un outil de compilation qui prend des définitions de jetons de design au format JSON et les produit dans n’importe quel format cible : propriétés personnalisées CSS, modules ES JavaScript, variables Sass, constantes Swift pour iOS, ressources XML pour Android et tout format personnalisé que vous définissez. Une seule source de vérité, de nombreuses sorties.

Installez-le avec npm install --save-dev style-dictionary. Initialisez la structure d’un projet avec npx style-dictionary init ; cette commande crée un fichier config.json (ou config.js) ainsi qu’un répertoire tokens/. La configuration indique à Style Dictionary où trouver les fichiers de jetons et où écrire les sorties.

Style Dictionary utilise une structure JSON imbriquée dont les nœuds terminaux possèdent une propriété value. Par exemple : { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Le chemin vers la valeur (couleur, primaire, 500) devient le nom du jeton après transformation, généralement au format color-primary-500 ou --color-primary-500.

Exécutez npx style-dictionary build --config config.json (ou style-dictionary build si la commande est configurée dans les scripts de package.json). Style Dictionary lit tous les fichiers de jetons depuis la source configurée, applique les transformations et écrit les sorties dans les destinations configurées. Les erreurs de format des jetons sont signalées avec le nom du fichier et le chemin.

Le fichier config.json définit les plateformes : css (produit un fichier CSS contenant des propriétés personnalisées), js (produit un objet JS) et scss (produit des variables Sass). Chaque plateforme précise le répertoire de sortie, le nom du fichier, le format (le modèle) et les transformations (les fonctions de traitement du nom et de la valeur) à appliquer.

Style Dictionary inclut des transformations intégrées : name/cti/kebab convertit le chemin imbriqué en color-primary-500, name/cti/camel produit colorPrimary500, size/rem convertit les valeurs en pixels en rem et color/hex normalise les couleurs au format hexadécimal. Les transformations peuvent être composées et sont appliquées dans l’ordre.

Vous pouvez enregistrer des transformations personnalisées avec StyleDictionary.registerTransform(). Par exemple, une transformation qui convertit les valeurs en pixels en points iOS, ou une autre qui ajoute un préfixe propre à l’entreprise à tous les noms de jetons. Les transformations personnalisées vous donnent un contrôle total sur le traitement des valeurs avant leur sortie.

Les formats personnalisés définissent le modèle du fichier de sortie. StyleDictionary.registerFormat() reçoit le dictionnaire des jetons transformés et renvoie une chaîne : le contenu du fichier. Vous pouvez produire les jetons sous forme de types TypeScript, d’un objet de thème React, d’une extension de configuration Tailwind ou de tout autre format requis par votre environnement.

Après la compilation, importez la sortie CSS dans votre feuille de style globale : @import './tokens/tokens.css'. Importez la sortie JS dans vos composants ou dans la configuration Tailwind : import tokens from './tokens/tokens.js'. La sortie CSS fournit des propriétés personnalisées pour la thématisation à l’exécution ; la sortie JS fournit des constantes typées pour Tailwind et la logique JavaScript.

Style Dictionary prend en charge les références de jetons utilisant des accolades : { "value": "{color.primary.500}" }. Cela crée des alias de jetons sémantiques : le jeton sémantique fait référence à un jeton primitif. Au moment de la compilation, Style Dictionary résout les références et produit la valeur finale résolue (ou une référence de variable CSS, selon votre format).

Exécutez Style Dictionary comme script npm prebuild afin que les jetons soient toujours régénérés avant la compilation de l’application. Ajoutez "prebuild": "style-dictionary build" à package.json. Cela garantit que toute modification apportée aux fichiers JSON des jetons est répercutée dans les sorties CSS et JS avant que la compilation React ne les traite.

À quoi servent les transformations dans Style Dictionary ?

Style Dictionary convertit le JSON des jetons dans n’importe quel format de sortie : variables CSS, modules JS, Sass, iOS et Android. Le JSON des jetons utilise des objets imbriqués dont les nœuds terminaux contiennent value. Les transformations traitent les noms et les valeurs (camelCase, conversion des px en rem) ; les formats définissent le modèle de sortie. Les références de jetons ({color.primary.500}) permettent de créer des alias sémantiques. Automatisez le processus avec un script prebuild afin que les jetons soient toujours à jour avant la compilation React.