Synchroniser des design tokens entre Figma, un dépôt Git et un pipeline CI sans générer de conflits est un besoin récurrent dans les équipes produit. J’ai expérimenté plusieurs approches chez des clients et sur mes propres projets, et je veux partager un workflow pragmatique qui minimise les frictions, garde une source de vérité claire et permet aux designers et développeurs de travailler en parallèle sans se marcher sur les pieds.

Principe de base : une seule source de vérité, mais des chemins d’écriture clairs

Le point clé est d’accepter une source de vérité principale pour les tokens — souvent Figma pour la majorité des équipes produit — tout en permettant des modifications via Git quand nécessaire. Concrètement : je considère Figma (via un plugin) comme l’interface de design principale et Git comme le stockage versionné et le pipeline de distribution. Mais surtout, je définis des règles précises sur qui peut éditer quoi et comment les changements remontent.

Outils que j’utilise et pourquoi

  • Figma + plugin Figma Tokens (ou Tokens Studio) : permet d’exporter et d’importer des tokens structurés (JSON) et de maintenir une bibliothèque partagée.
  • Style Dictionary (Amazon) : transforme les tokens en formats destinés aux plateformes (CSS variables, SCSS, Android XML, iOS Swift).
  • Git (GitHub/GitLab) : héberge les tokens versionnés et sert de centre de distribution.
  • CI (GitHub Actions / GitLab CI) : automatise les builds, validations et publications (npm, artifactory, CDN).
  • Un petit script de normalisation (Node.js) : applique un ordre, nettoie les métadonnées et génère un hash pour détection de changement.

    • Structure de fichiers recommandée

    Une organisation claire des fichiers réduit les conflits. Voici une structure que j’ai adoptée :

    Chemin Contenu
    /tokens/source/figma.json Export brut depuis Figma (single source JSON)
    /tokens/normalized/tokens.json Fichier nettoyé et trié (format canonique pour Style Dictionary)
    /build/* Fichiers générés (CSS, SCSS, iOS, Android)
    /scripts/ Scripts d’import/export et de normalisation

    Workflow détaillé — de la modification à la publication

    Voici le flux que j’applique et que je recommande de documenter dans le README du repo :

  • 1) Modification dans Figma : un designer modifie un token (couleur, spacing, etc.) dans la bibliothèque partagée.
  • 2) Export Figma → Git : le designer utilise le plugin Figma Tokens pour exporter le fichier JSON et ouvre une MR/PR vers la branche feature/token-update.
  • 3) Normalisation automatique (pre-merge CI) : une GitHub Action déclenche le script de normalisation qui :
  • - trie les clés
  • - retire les métadonnées temporaires
  • - ajoute un champ hash (sha1) pour le contenu
  • 4) Validation : la CI exécute des checks : lint JSON, schéma JSON (ajout d'errors sur breaking changes), tests visuels si possible.
  • 5) Build : si tout passe, Style Dictionary génère les artefacts pour chaque plateforme et commit auto-build dans une branche dédiée (/build ou release).
  • 6) Merge : PR revue et merge. Si la normalisation a modifié le fichier, la PR montre uniquement les diffs « utiles ».
  • 7) Publication : la CI publie les artefacts (npm package, CDN, ou artefact interne).

    • Comment éviter les conflits Git

    Les conflits surviennent souvent parce que deux personnes exportent des fichiers JSON non-ordonnés ou avec métadonnées différentes. Pour cela :

  • Centraliser l’export : encouragez l’usage d’un seul plugin/config d’export (Figma Tokens) et documentez le format exact.
  • Normaliser automatiquement : chaque PR doit passer par un job qui réécrit le JSON selon un canon (ordre alphabétique, suppression des champs volatiles). Le diff sera stable.
  • Employer un lock commit : après génération, la CI peut ajouter un commit unique contenant le build. Les développeurs pullent toujours cette branche build avant de travailler dessus.
  • Petites PRs : limitez une PR à un petit ensemble de tokens. Les gros dumps créent inévitablement des conflits.

    • Strategy Git et règles de merge

    J’applique ces règles opérationnelles :

  • Branche principale : main/master doit rester propre et ne contient que des merges validés par CI.
  • Branches feature : chaque modification de tokens doit se faire dans une branche dédiée nommée feature/tokens/nom.
  • Rebases fréquents : demandez aux auteurs de PR de rebase régulièrement pour réduire les conflits. Notre CI vérifie que la branche est à jour avant merge.
  • PR templates : inclure un checklist obligatoire pour l’auteur : "J’ai exporté depuis Figma", "Mon export a été normalisé avec le script", "Les tests CI passent".

    • Gérer les changements breaking

    Pour les changements qui cassent les implémentations (par exemple suppression d’un token), je recommande :

  • Versionner les tokens : semantic versioning for tokens (major.minor.patch). Une modification breaking bump la major.
  • Deprecation policy : plutôt que supprimer un token immédiatement, le marquer comme deprecated dans Figma et dans le JSON, laisser un cycle de vie (ex: 2 sprints) puis supprimer.
  • Checks CI stricte : détecter les suppressions et avertir automatiquement les équipes concernées via Slack ou issue.

    • Automatisations CI que j’ai mises en place

    Genre de tâches automatisées dans GitHub Actions :

  • job: normalize — exécute node scripts/normalize.js sur l’export et commit si modifications
  • job: lint — schéma JSON et conventions (naming tokens)
  • job: build — Style Dictionary build pour CSS/Android/iOS
  • job: publish — publish vers registry interne ou npm si tag release
  • job: notify — envoie un message (Slack/MS Teams) décrivant les tokens modifiés

    • Exemple de script de normalisation (concept)

    Voici l’idée : charger le JSON, trier récursivement les clés, supprimer les champs non essentiels, calculer un hash. Ça rend chaque export déterministe et minimise les diffs inutiles.

    Conseils pour la collaboration designers/devs

  • Documentez le flux dans le repo et dans la bibliothèque Figma : qui peut modifier les tokens, comment exporter, comment ouvrir une PR.
  • Ateliers réguliers : faites des revues de tokens toutes les 2-3 semaines pour aligner naming et usages.
  • Créer des stories ou tickets associés à chaque changement de token important — relier la PR au ticket pour traçabilité.

    • Quand autoriser des modifications directement dans Git

    Parfois un dev doit corriger un token pour une urgence (bug visuel). Dans ce cas :

  • Autoriser des PRs dev-to-tokens mais avec une exigence : inclure un screenshot, raison du changement, et créer une tâche pour synchroniser vers Figma (ou faire la modification dans Figma après merge).
  • Automatiser une tâche qui injecte ces changements dans un espace "pending" visible par les designers pour revue et import dans Figma.

    • Ce workflow n’est pas une religion : il faut l’adapter à la taille de l’équipe et au degré de maturité. L’important est de réduire les opérations humaines répétitives (normalisation, build, publication) et de créer une chaîne de confiance entre Figma et Git via la CI. Si vous souhaitez, je peux partager un exemple concret de GitHub Actions + scripts Node.js pour démarrer rapidement sur votre repo.