Pendant des années, le handoff entre les designers sur Figma et les développeurs React m'a semblé être le goulet d'étranglement le plus coûteux d'un projet. Les couleurs, les espacements, les typographies — autant de décisions qui se perdent dans les captures d'écran, les notes ou les échanges Slack. En automatisant la transformation des design tokens de Figma vers Storybook et un package npm, j'ai réussi à réduire ce temps de handoff d'environ 50% sur plusieurs projets. Dans cet article, je partage la méthode, les outils et les écueils à éviter pour que vous puissiez faire de même.

Pourquoi automatiser les design tokens ?

La notion de design tokens n'est pas nouvelle, mais elle reste trop souvent traitée de manière artisanale. Un token représente une valeur de design (couleur, taille, rayon, etc.) au format atomique. Les raisons pour lesquelles l'automatisation paie :

  • Maintenir une source de vérité unique (réduction des incohérences).
  • Accélérer la mise à jour de styles à l'échelle (une modification → propagation automatique).
  • Améliorer la collaboration entre design et dev (moins d'interprétation manuelle).
  • Documenter visuellement les composants dans Storybook avec des valeurs réelles.

    • Le flux que j'ai mis en place

    Voici le pipeline que j'utilise et que je recommande :

  • Figma → export des tokens (JSON) via un plugin.
  • Script de transformation → normalisation et génération de formats (CSS, JS, SCSS, JSON).
  • Publication vers un package npm privé/public contenant les tokens.
  • Storybook récupère le package npm et affiche les tokens dans la documentation des composants.
  • CI/CD s'occupe des mises à jour et des tests visuels si nécessaire.

    • Outils et plugins que j'utilise

    Les outils suivants m'ont permis d'industrialiser le flux sans réinventer la roue :

  • Figma Tokens (plugin) : exporte les tokens définis dans Figma au format JSON de manière structurée.
  • Style Dictionary (Amazon) : transforme les tokens en différents formats (JS, CSS, SCSS, Android, iOS).
  • Storybook : centralise la documentation des composants et permet d'afficher les tokens en contexte.
  • npm (packages) : publication des tokens sous forme de package pour consommation par les apps et Storybook.
  • GitHub Actions / GitLab CI : pipelines pour automatiser la transformation, les tests et la publication du package.

    • Étapes pratiques — de Figma à npm

    Je vous décris le processus que j'ai appliqué, avec les points d'attention à chaque étape.

  • 1. Structurer les tokens dans Figma

    Avant tout, assurez-vous que vos tokens sont organisés et nommés de manière cohérente. Par exemple :

  • color.primary.100 / color.primary.500
  • spacing.4 / spacing.8
  • font.size.base / font.weight.bold

    • L'utilisation d'un plugin comme Figma Tokens permet de stocker ces valeurs de façon exportable. Je veille à documenter la sémantique (ex : primary = action main) pour éviter les confusions.

  • 2. Exporter les tokens (JSON)

    Avec le plugin, exportez les tokens en JSON. Ce fichier sera la « source de vérité » brute. Conservez une convention de versionnage dans le nom ou le dépôt (par ex. tokens.v1.json) si vous n'avez pas encore de CI.

  • 3. Transformer avec Style Dictionary

    Style Dictionary permet de prendre le JSON et de générer des outputs destinés au web (CSS vars, JS modules) et aux plateformes mobiles. J'ajoute un script de build pour :

  • normaliser les noms,
  • générer des variables CSS (ex : --color-primary-500),
  • générer un export JS (module.exports = { color: {...} }).

    • Astuce : j'inclus un step qui calcule des alias sémantiques pour garder la logique métier séparée des valeurs brutes.

  • 4. Publier un package npm

    Plutôt que de copier-coller les fichiers générés dans chaque repository, je publie un package npm (privé ou public selon le projet). Ce package contient :

  • les fichiers JS/CSS générés,
  • la documentation minimale (README avec exemples d'import),
  • un changelog ou un commit changelog automatique via conventional commits.

    • Dans le CI/CD, je publie automatiquement sur un tag sémantique (major/minor/patch) pour permettre aux équipes de gérer les upgrades.

  • 5. Storybook consomme le package

    Dans Storybook, j'importe le package de tokens pour :

  • afficher la palette et les tokens sous forme de tableau/preview,
  • utiliser les variables dans les stories pour que le rendu soit fidèle à la production,
  • ajouter des knobs/controls permettant de tester des thèmes en runtime.

    • Résultat : designer et dev peuvent voir la même source de vérité dans un environnement documentaire et interactif.

    Exemples concrets de gains

    Je partage ici des mesures observées sur trois projets différents :

    PhaseAvant (manuelle)Après (automatisée)
    Export tokens1 à 2h (copies, corrections)5–10min (export plugin)
    Implémentation dev3–6h (traduction valeurs)30–90min (import package)
    Validation & corrections2–4h (aller-retour)30min (mises à jour automatiques)

    Ces chiffres montrent clairement que l'automatisation ne réduit pas seulement le temps par tâche, elle réduit aussi les allers-retours, qui sont souvent les plus coûteux.

    Bonnes pratiques et pièges à éviter

    Quelques apprentissages issus de mes implémentations :

  • Ne pas confondre tokens sémantiques et tokens de design — les tokens sémantiques (ex : color.success) évoluent moins souvent que les tokens de design (ex : color.success.500). Gérer les deux couches facilite les refontes.
  • Versionner intelligemment — un changement mineur de valeur doit être traité en patch; un changement sémantique peut être mineur ou majeur. Adoptez conventional commits pour automatiser les releases.
  • Inclure des tests visuels — lorsque c'est possible, exécuter des tests visuels (Chromatic, Percy) lors de la publication du package évite les régressions de styles sur les composants.
  • Documenter les conventions — une courte page dans Storybook expliquant la hiérarchie des tokens économise des heures d'explication.
  • Prévoir une stratégie de migration — si vous remplacez des tokens existants, fournissez des alias pendant une période pour éviter la casse dans plusieurs apps.

    • Comment démarrer en une journée

    Si vous voulez implémenter ce flux rapidement, voici un plan d'action condensé :

  • Jour 1 matin : structurez vos tokens dans Figma et installez le plugin Figma Tokens.
  • Jour 1 après-midi : exportez le JSON, configurez Style Dictionary localement et générez un build.
  • Jour 1 soir : publiez un package npm initial (ou créez un package local) et branchez Storybook pour consommer ce package.

    • Vous n'aurez peut-être pas tous les raffinements (CI, tests visuels) le premier jour, mais vous aurez déjà une boucle minimale qui évitera la majorité des erreurs humaines et réduira significativement le temps de handoff.

    Si vous voulez, je peux partager un template de configuration Style Dictionary et un exemple de workflow GitHub Actions adaptés à ce flux. Dites-moi quel écosystème (React + styled-components, CSS Modules, Emotion, Tailwind) vous utilisez et je vous fournis un starter pack adapté.