Garder un système de design tokens cohérent entre Figma, Storybook et un package npm est devenu central pour maintenir des interfaces scalables. J'ai traversé plusieurs approches — du simple export manuel aux pipelines entièrement automatisés — et voici comment j'aborde aujourd'hui un pipeline de design tokens qui alimente Storybook et un package npm sans bloquer l'intégration continue.

Pourquoi automatiser les tokens sans bloquer la CI ?

Les tokens (couleurs, typographies, espaces, etc.) évoluent fréquemment. Si votre CI attend qu'un export manuel soit fait avant de construire Storybook ou de publier un package, vous vous retrouvez avec des builds cassés ou des délais inutiles. Mon objectif est d'avoir :

  • un flux automatique qui met à jour les tokens depuis Figma ;
  • une source de vérité versionnée (package npm) ;
  • un Storybook à jour pour les développeurs et designers ;
  • des builds CI robustes qui ne dépendent pas d'actions humaines pour démarrer.

Vue d'ensemble du pipeline

Voici le schéma que j'utilise :

  • Figma → export automatique (via plugin ou API)
  • transformations (format tokens, normalisations)
  • commit / PR automatique vers dépôt tokens (optionnel)
  • publication du package npm ou mise à jour d'un package internal
  • Storybook consomme le package npm (ou le repo tokens) à la build
  • CI (GitHub Actions / GitLab CI / CircleCI) construit sans blocage en utilisant le package versionné ou des artefacts pré-générés

Étape 1 — Extraire les tokens depuis Figma

Pour automatiser, j'utilise l'API Figma couplée à un petit script Node.js ou un service serverless. Il y a aussi des outils plug-and-play comme Figma Tokens (plugin open-source) qui offrent export JSON et des transformations. Les points clés :

  • Authentification via token personnel Figma (gardez-le dans les secrets CI)
  • Définir des tokens structurés dans Figma (noms cohérents : color.primary, space.4, typography.h1.size)
  • Exporter un JSON standard (structure simple et prévisible)

Exemple minimal d'appel dans un script Node :

const fetch = require('node-fetch');const FIGMA_TOKEN = process.env.FIGMA_TOKEN;const FILE_KEY = 'votre_file_key';const res = await fetch(`https://api.figma.com/v1/files/${FILE_KEY}`, {  headers: { 'X-Figma-Token': FIGMA_TOKEN }});const data = await res.json();// parsez et extrayez vos styles

Étape 2 — Transformer et valider

Une fois le JSON extrait, je transforme les données en formats utiles : JSON standard pour le package, CSS variables, SCSS maps, ou JS export pour les tokens JS. J'ajoute aussi une validation pour éviter d'envoyer des valeurs invalides en CI.

  • Normaliser les couleurs (hex, rgba)
  • Vérifier les doublons et les clés manquantes
  • Générer plusieurs sorties : tokens.json, tokens.css, tokens.js

Un petit extrait de transformation :

function toCssVars(tokens) {  return Object.entries(tokens).map(    ([key, value]) => `--${key.replace(/\./g,'-')}: ${value};`  ).join('\n');}

Étape 3 — Où stocker les tokens ? package npm vs dépôt mono-repo

J'ai testé deux approches :

  • Package npm privé/public : pratique pour la distribution, versionnage clair via semver ; parfait si plusieurs projets consomment les mêmes tokens.
  • Dépôt de tokens (monorepo ou repo séparé) : préférable si vous voulez plus de contrôle, PRs humaines et historique des changements.

Pour éviter que la CI soit bloquée, la règle que j'applique est : toujours dépendre d'une version publiée ou d'un artefact stable lors d'une build CI. Ne laissez pas la build dépendre d'une génération en temps réel depuis Figma.

Étape 4 — Automatiser les mises à jour (sans blocage)

Voici mon workflow automatisé qui évite les blocages :

  • Un scheduler (GitHub Actions cron, serverless function ou webhook) extrait et transforme les tokens régulièrement (par ex. toutes les heures ou à chaque push sur une branche Figma) ;
  • Le job crée une PR automatique dans le repo tokens avec le JSON mis à jour (utilisez bots comme renovate style ou GitHub Apps) ;
  • Un pipeline de validation (tests unitaires, lint tokens) s'exécute sur la PR ;
  • Après approbation (automatique si validation OK) le CI publie une nouvelle version du package npm ;
  • Les projets consommateurs peuvent soit suivre le canal "latest" soit utiliser des ranges semver pour contrôler les updates.

Important : je ne fais pas construire Storybook à partir d'un export Figma "on-demand" durant le pipeline principal. Storybook récupère le package npm publié — ainsi la build n'attend pas Figma et ne bloque pas.

Étape 5 — Intégrer Storybook

Dans Storybook, je préfère importer les tokens depuis le package npm. Exemple dans .storybook/preview.js :

import tokens from 'mon-design-tokens';import './tokens.css';export const parameters = {  // ...};

Si vous avez besoin d'un aperçu live des changements Figma avant publication, vous pouvez :

  • Déployer un Storybook preview stage qui consomme la branche tokens du repo (CI/CD séparé) ;
  • Ou utiliser un tag "next" sur npm pour tester les changements sans impacter la production.

Conseils pratiques pour éviter les pièges

  • Secrets et permissions : stockez le token Figma et les credentials npm dans les secrets CI (GitHub Secrets, GitLab CI variables).
  • Builds idempotents : chaque pipeline doit réussir avec les mêmes inputs ; évitez les appels réseaux non déterministes durant la build principale.
  • Versioning clair : utilisez semver et changelogs automatiques (par ex. conventional commits + semantic-release) pour déclencher publications non bloquantes.
  • Fallbacks : si le service d'extraction échoue, la publication s'arrête mais les builds consommateurs utilisent la dernière version publiée — pas de casse.
  • Tests visuels : ajoutez Percy/Chromatic pour détecter les régressions UI suite aux changements de tokens.

Exemple de GitHub Action minimal

Voici un workflow d'exemple qui extrait, valide, ouvre une PR et publie si tout est vert (schématique) :

name: Update Design Tokenson:  schedule:    - cron: '0 * * * *' # chaque heurejobs:  fetch:    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v3      - name: Export from Figma        run: node scripts/export-figma.js        env:          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}      - name: Run validations        run: npm run validate-tokens      - name: Create PR        uses: peter-evans/create-pull-request@v4        with:          commit-message: 'chore(tokens): update from Figma'

Routines de confiance

Ce qui marche le mieux pour moi, c'est la séparation claire des responsabilités : extraction (asynchrone et planifiée), publication (automatique après validation), consommation (projects build à partir d'une version publiée). Ainsi, la CI de mes projets n'est jamais dépendante d'une opération externe immédiate et les équipes peuvent collaborer sur les updates via PRs lorsque c'est nécessaire.

Checklist rapide pour démarrer

  • Structurer les tokens dans Figma avec des noms cohérents
  • Créer un script d'export (ou utiliser Figma Tokens)
  • Mettre en place validation et tests
  • Automatiser PRs et publications npm
  • Configurer Storybook pour consommer le package npm
  • Ajouter monitoring/alertes en cas d'échec d'export

Si tu veux, je peux te fournir un repo d'exemple (scripts + GitHub Actions) adapté à ton contexte, ou examiner ta configuration actuelle et indiquer où découpler les étapes pour éviter les blocages CI. Dis-moi quelle stack CI et gestion de packages tu utilises (GitHub/GitLab, npm privé/public, monorepo ou multi-repo) et je te propose un plan concret.