Synchroniser les design tokens entre Figma et le code, c'est un sujet qui revient sans cesse dans mes projets. J'aime l'idée d'avoir une source de vérité visuelle dans Figma et de la propulser automatiquement dans les librairies front, Storybook ou les systèmes de design code. Quand c'est bien fait, ça réduit les erreurs, accélère le développement et garde l'interface cohérente. Dans cet article, je décris une approche pratique, outils et patterns que j'utilise pour automatiser cette synchronisation.

Pourquoi automatiser les tokens ?

Les tokens — couleurs, typographies, espacements, radii, ombres — sont la base d'un design system. Les maintenir manuellement fait double emploi : designer et dev se retrouvent à recréer les mêmes valeurs, avec des variations et des erreurs. L'automatisation apporte :

  • Une source de vérité unique (Figma) synchronisée avec le code.
  • Des exports formatés pour CSS variables, JSON, SCSS, Tailwind, etc.
  • Un workflow reproductible intégré à CI/CD pour déployer des changements en toute confiance.

    • Choisir les bons outils

    Il existe plusieurs solutions et le choix dépend du niveau d'intégration que vous voulez :

  • Figma Tokens (plugin officiel/community) : excellent pour gérer les tokens dans Figma et les exporter en JSON.
  • Tokens Studio : plugin puissant avec versioning et compatibilité multi-platforme.
  • Style Dictionary (Amazon) : convertit des tokens JSON en formats multiples (CSS, SCSS, iOS, Android, JS).
  • Theo : alternative à Style Dictionary, moins active mais utile dans certains stacks.
  • Token Transformer / custom scripts : pour des transformations spécifiques (naming, mesures, rem/px conversion).
  • CI/CD : GitHub Actions, GitLab CI, CircleCI pour automatiser l'export et la publication.
  • Storybook / npm packages : pour consommer et documenter les tokens côté composants.

    • Flux de travail que j'implémente

    Voici un workflow que j'applique sur la plupart des projets. Il s'agit d'une chaîne simple mais robuste entre Figma et le dépôt de code :

  • Gérer les tokens dans Figma (via Figma Tokens ou Tokens Studio).
  • Exporter les tokens en JSON (manuellement ou via l'API de Figma / plugin).
  • Committer ce JSON dans un dépôt (souvent un monorepo ou un package npm : @design-system/tokens).
  • Utiliser Style Dictionary pour générer des fichiers finales (CSS vars, JS, SCSS, tokens Tailwind).
  • Publier automatiquement le package ou merger une PR via CI.
  • Consommer les tokens dans l'app / Storybook / design system components.

    • Étapes techniques détaillées

    1. Structurer les tokens dans Figma

    Je crée une hiérarchie claire : couleurs (brand, semantic, neutral), typographie (families, scales), spacing, radii, shadows. Si vous utilisez Figma Tokens, définissez des catégories et noms explicites comme color.brand.primary ou size.spacing.8. La convention de nommage est cruciale pour des transformations propres.

    2. Exporter depuis Figma

    Deux options :

  • Exporter manuellement via le plugin en JSON et commit dans le repo.
  • Utiliser l'API Figma + un script CI pour récupérer automatiquement le fichier (utile pour des mises à jour fréquentes).

    • Exemple de payload JSON (simplifié) :

    {"color": {"brand": {"primary": "#0d6efd"}, "semantic": {"success": "#198754"}}}

    3. Centraliser les tokens dans un package

    Je crée un package npm privé/public @mon-projet/tokens qui contient le JSON source et la config de transformation (Style Dictionary). Cela permet de versionner les tokens et d'avoir des releases.

    4. Transformer avec Style Dictionary

    Style Dictionary permet de mapper les tokens vers différents formats via des transformations et des templates. Exemple de config :

    { "source": ["tokens/*.json"], "platforms": { "css": { "transformGroup": "css", "buildPath": "dist/css/", "files": [{"destination": "variables.css", "format": "css/variables"}] }, "js": { "transformGroup": "js", "buildPath": "dist/js/", "files": [{"destination": "tokens.js", "format": "javascript/es6"}] } }}

    Je rajoute des transforms personnalisés si besoin (par ex. conversion px → rem, normalisation des couleurs).

    5. Automatiser via CI

    J'ajoute une GitHub Action qui :

  • Récupère la dernière exportation Figma (si automatisée),
  • Exécute Style Dictionary pour générer les fichiers,
  • Commit/Push vers une branche ou publie le package npm et crée une release.

    • Un workflow simple : push sur branche tokens → action build tokens → PR automatique vers main avec les modifications générées. Ainsi les changements passent en revue avant merge.

    Consommer les tokens dans le code

    Selon vos besoins, vous pouvez exposer :

  • CSS variables (:root) pour consommation directe dans les styles, utilitaires et dans Storybook.
  • JS modules pour frameworks (React, Vue) : export d'un objet tokens.
  • Intégrations Tailwind : générer un fichier de configuration pour injecter les couleurs et spacing.

    • Exemple d'usage CSS :

    --color-brand-primary: #0d6efd;

    Dans un composant React je peux alors importer les tokens JS pour styler via styled-components ou utiliser les variables CSS directement.

    Bonnes pratiques et pièges à éviter

  • Garder les tokens atomiques : évitez les tokens « composants » avec des valeurs composites. Les tokens doivent être réutilisables.
  • Versionner tout : le JSON source et les builds doivent être traçables via tags/versions.
  • Nommer pour la réutilisation : préférez des noms sémantiques (color.background.primary) plutôt que des noms purement visuels (bleu-1).
  • Tests visuels : chaque mise à jour des tokens mérite une vérification (Storybook snapshots, visual regression).
  • Ne pas tout automatiser aveuglément : j’aime que les changements importants passent par une PR et une revue design+dev.

    • Cas pratiques

    Sur un projet récent, j'ai mis en place :

  • Figma Tokens pour gérer et versionner les tokens dans Figma.
  • Un script Node qui interroge l'API Figma et exporte le JSON dans le dépôt tokens via une GitHub Action planifiée.
  • Style Dictionary pour générer : CSS variables, tokens JS et un fichier de configuration Tailwind.
  • Une GitHub Action qui publie une release du package tokens à chaque merge sur main.

    • Résultat : l'équipe produit pouvait ajuster une couleur dans Figma, ouvrir une PR, et en 10 minutes le package tokens était prêt à être consommé par les composants. La transparence et la traçabilité ont réduit les allers-retours.

    Outils complémentaires

    Voici quelques outils que j'utilise selon le contexte :

  • Design tokens Transformer (pour conversions avancées)
  • Chromatic ou Percy pour visual testing
  • Storybook + addon-docs pour documenter l'usage des tokens auprès des devs
  • NPM private registry (GitHub Packages) pour partager les tokens facilement

    • Si vous voulez, je peux préparer un exemple de repo minimal (Figma export JSON + config Style Dictionary + GitHub Action) pour démarrer rapidement. Dites-moi votre stack (React, Vue, Tailwind, plain CSS) et j'adapte les fichiers de sortie et le workflow.