Générer ses design tokens en CSS, JS et SCSS avec Style Dictionary

Vous avez un fichier tokens.json propre — mais un fichier JSON ne colore aucun bouton. Il faut le transformer en quelque chose que vos plateformes comprennent : des variables CSS pour le web, un module JavaScript pour React, des variables SCSS pour une base existante. Recopier ces valeurs à la main pour chaque cible, c’est rouvrir la porte aux incohérences. Style Dictionary automatise ce passage : un seul jeu de tokens, autant de sorties que de plateformes, générées par une commande.

🎯 Ce que vous allez apprendre

• Comprendre le pipeline de Style Dictionary : source → transforms → format → fichiers.
• Écrire une configuration en ES Modules pour Style Dictionary 4.
• Générer en une commande des variables CSS, un module JavaScript et des variables SCSS depuis le même fichier de tokens.
• Comprendre comment les références entre tokens ({color.blue.600}) sont résolues automatiquement à la compilation.
• Brancher la génération dans un script npm pour l’intégrer à votre flux de travail.

🛠️ Ce que vous allez construire

Un dossier build/ qui contient css/variables.css, js/tokens.js et scss/_variables.scss, tous dérivés de tokens/figma.tokens.json. Une commande npm run tokens régénérera l’ensemble. Modifier une couleur dans Figma, réextraire, relancer le build : la nouvelle valeur se propagera partout, sans intervention manuelle.

Prérequis

• Node.js 20+ et npm.
• Le fichier tokens/figma.tokens.json issu du tutoriel précédent. Si vous ne l’avez pas, n’importe quel fichier au format W3C (propriétés $value / $type) fait l’affaire.
• Des notions de ligne de commande. Test express : si vous savez lancer npm init -y, vous êtes prêt.
• ⏱️ Temps estimé : ~35 minutes.

Étape 1 — Installer et comprendre le pipeline

Avant de configurer quoi que ce soit, il faut un modèle mental clair. Style Dictionary lit vos tokens, leur applique une suite de transforms (transformations atomiques : convertir une couleur, mettre un nom en kebab-case, ajouter une unité), puis assemble le résultat avec un format (le gabarit du fichier de sortie). On installe l’outil en dépendance de développement :

npm init -y
npm install --save-dev style-dictionary

Style Dictionary 4 est entièrement réécrit en ES Modules et possède un support de première classe du format W3C : il lit directement vos fichiers en $value / $type sans conversion préalable. Retenez la chaîne source → transforms → format → files : chaque cible (CSS, JS, SCSS) est une plateforme qui choisit son groupe de transforms et ses formats. C’est tout le modèle.

Étape 2 — Écrire la configuration

La configuration décrit d’où viennent les tokens et quelles sorties produire. On l’écrit dans un fichier style-dictionary.config.js. Commençons par une seule plateforme pour valider la chaîne avant de l’étendre :

// style-dictionary.config.js
export default {
  source: ['tokens/**/*.tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [
        { destination: 'variables.css', format: 'css/variables' }
      ]
    }
  }
};

Décortiquons. source est un motif glob : tous les fichiers de tokens du dossier seront fusionnés en un seul arbre. platforms.css déclare une cible : transformGroup: 'css' applique l’ensemble des transforms adaptées au web (couleurs en hexadécimal, noms en kebab-case), buildPath est le dossier de sortie (la barre oblique finale est obligatoire), et files liste les fichiers à écrire avec leur format. Ici, css/variables produit un bloc :root de variables CSS.

Étape 3 — Lancer le premier build

On peut maintenant générer. Style Dictionary expose une commande qui lit la configuration par défaut :

npx style-dictionary build

La console affiche, pour chaque plateforme, les fichiers écrits. Ouvrez build/css/variables.css : vous devez y trouver quelque chose comme ceci :

:root {
  --color-surface: #ffffff;
  --color-action: #2563eb;
  --space-md: 16px;
}

Observez le nom : color/surface dans Figma est devenu --color-surface. C’est le transform de nommage du groupe css qui a aplati le chemin en kebab-case. Si vous voyez ce fichier, la chaîne complète fonctionne. Un message signalant qu’aucun token n’a été trouvé indique que le motif source ne correspond à aucun fichier : vérifiez le chemin et l’extension.

✅ Point d’étape — Vous avez un variables.css généré avec des noms en kebab-case et des couleurs en hexadécimal. Pour vérifier : cat build/css/variables.css. Si le fichier existe mais est vide, vos tokens n’ont pas de $value reconnaissable.

Étape 4 — Comprendre ce que font les transforms

Le « miracle » de l’étape précédente mérite une explication, car c’est là que se joue la portabilité. Un transform agit sur un seul aspect d’un token. Le groupe css en enchaîne plusieurs : un transform de couleur convertit l’objet de couleur en chaîne hexadécimale, un transform de nom aplatit le chemin en --color-surface, un transform de dimension garantit l’unité px. Le groupe js, lui, produit des noms en PascalCase et des valeurs prêtes pour du code. C’est pourquoi un même token donne --color-surface en CSS et ColorSurface en JavaScript : ce ne sont pas deux définitions, mais deux vues transformées du même token. Vous n’avez rien à coder pour cela ; il suffit de choisir le bon transformGroup par plateforme.

Étape 5 — Ajouter les cibles JavaScript et SCSS

Une seule plateforme ne montre pas l’intérêt de l’outil. Ajoutons deux cibles pour couvrir un projet React et une base SCSS existante. On complète platforms :

export default {
  source: ['tokens/**/*.tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{ destination: 'variables.css', format: 'css/variables' }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'build/js/',
      files: [{ destination: 'tokens.js', format: 'javascript/es6' }]
    },
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/scss/',
      files: [{ destination: '_variables.scss', format: 'scss/variables' }]
    }
  }
};

Relancez npx style-dictionary build. Vous obtenez maintenant trois fichiers. Le module JavaScript exporte des constantes (export const ColorSurface = "#ffffff";) que vous importez dans vos composants ; le fichier SCSS déclare des $color-surface: #ffffff; consommables par vos feuilles existantes. Le point essentiel : les trois sorties proviennent du même fichier source. Une couleur changée à la source se répercute sur les trois en un seul build.

Étape 6 — Résolution automatique des références

Souvenez-vous des alias du tutoriel précédent : un token sémantique comme color.action pointe vers une primitive via {color.blue.600}. Style Dictionary résout ces références à la compilation. Vous n’obtenez jamais {color.blue.600} dans le CSS final, mais la valeur réelle #2563eb. C’est précisément le comportement souhaité : vos tokens restent sémantiques et lisibles à la source, tandis que la sortie est concrète et autonome. Si une référence pointe vers un token inexistant, le build échoue avec un message Reference doesn't exist — un garde-fou utile contre les fautes de frappe.

✅ Point d’étape — Vos trois fichiers contiennent des valeurs résolues, pas des accolades. Cherchez une chaîne { dans build/css/variables.css : vous ne devez en trouver aucune (hors le :root {).

Étape 7 — Intégrer au flux de travail

Taper npx style-dictionary build à la main est fragile. On déclare un script npm pour que la génération devienne une commande de projet, réutilisable en local comme en intégration continue. Dans package.json :

{
  "scripts": {
    "tokens": "style-dictionary build",
    "tokens:sync": "node fetch-tokens.mjs && style-dictionary build"
  }
}

Désormais, npm run tokens régénère les sorties, et npm run tokens:sync enchaîne l’extraction Figma (script du tutoriel précédent) puis le build. C’est la commande que vous lancerez après chaque évolution de la charte. En intégration continue, le même script garantit que les tokens livrés correspondent toujours à la dernière maquette validée.

Organiser ses tokens en trois niveaux

Un pipeline qui fonctionne techniquement peut quand même devenir ingérable si les tokens sont mal structurés. La pratique éprouvée consiste à les répartir en trois niveaux, du plus brut au plus contextuel, et Style Dictionary s’accommode parfaitement de cette organisation puisqu’il fusionne tous les fichiers source en un seul arbre.

Le premier niveau regroupe les primitives : la palette nue, sans intention. Ce sont des valeurs comme color.blue.600 ou size.4, qui décrivent ce qu’est la valeur, jamais à quoi elle sert. Une primitive ne devrait jamais apparaître directement dans un composant : elle est trop générique, et la lier à un usage précis rendrait tout changement de thème impossible. On la garde comme réservoir.

Le deuxième niveau est celui des tokens sémantiques : ils donnent du sens en pointant vers des primitives. color.action référence {color.blue.600}, color.surface référence un neutre, space.inset.md référence {size.4}. C’est ce niveau que consomme votre code. L’intérêt est décisif : pour passer toute l’interface en thème sombre, on ne touche qu’aux sémantiques, jamais aux composants. Le jour où la marque change son bleu d’action, on modifie une seule référence et la propagation est automatique à la compilation.

Le troisième niveau, optionnel, est celui des tokens de composant : button.background, card.border. Ils pointent vers des sémantiques et permettent d’ajuster un composant précis sans perturber le reste. On ne les introduit que lorsqu’un composant a des besoins propres ; les ajouter trop tôt alourdit le système sans bénéfice.

Cette hiérarchie n’est pas un caprice d’architecture : elle correspond à la manière dont une charte évolue réellement. Les primitives bougent rarement, les sémantiques portent les décisions de design, les composants absorbent les exceptions. En séparant les fichiers — primitives.tokens.json, semantic.tokens.json, component.tokens.json — vous gardez une source lisible, et le motif source de votre configuration les agrège sans effort. C’est la même logique que celle d’un code bien découpé : chaque niveau a une responsabilité unique, et les dépendances vont toujours du plus contextuel vers le plus brut, jamais l’inverse.

🐞 Pièges fréquents

✅ Récapitulatif

Vous transformez désormais un unique fichier de tokens en variables CSS, module JavaScript et variables SCSS, le tout par une commande. Vous comprenez le pipeline source → transforms → format → fichiers, vous savez choisir un transformGroup par plateforme, et vous laissez l’outil résoudre les références sémantiques. La charte n’existe plus qu’à un seul endroit ; le reste en découle mécaniquement.

🧾 Aide-mémoire

💪 À vous de jouer

Ajoutez une quatrième plateforme qui produit un fichier build/css/dark.css à partir d’un second fichier de tokens (le mode sombre exporté à l’exercice du tutoriel précédent), en enveloppant les variables dans un sélecteur [data-theme="dark"] plutôt que :root.

Tutoriels de la série

• Extraire les design tokens depuis Figma avec l’API Variables — l’étape qui produit le fichier d’entrée.
• Relier composant Figma et composant React avec Dev Mode et Code Connect — l’autre pont design-code.

Pour aller plus loin

• 🔝 Retour au guide principal : Du design au code : Figma, tokens et WCAG 2.2.
• Documentation officielle : styledictionary.com.

FAQ

Style Dictionary 4 lit-il vraiment le format W3C sans conversion ?
Oui, la version 4 prend en charge nativement les tokens en $value / $type. Notez qu’on ne mélange pas les deux formats (l’ancien value et le nouveau $value) dans une même instance.

Faut-il commiter le dossier build/ ?
C’est un choix d’équipe. Beaucoup l’ignorent dans Git et le régénèrent à la compilation, comme tout artefact dérivé. D’autres le versionnent pour faciliter la revue des changements de valeurs.

Et pour iOS ou Android ?
Le principe est identique : on ajoute une plateforme avec le transformGroup et les formats adaptés (par exemple des ressources pour Android). Le fichier de tokens, lui, ne change pas.

Peut-on créer ses propres transforms ?
Oui. Style Dictionary 4 regroupe les extensions sous la clé hooks ; on y enregistre des transforms, formats ou filtres maison quand les transforms intégrés ne suffisent pas.