Synchroniser des design tokens entre Figma, Zeroheight et un dépôt de code sans provoquer de conflits pour les développeurs, c'est un défi fréquent que j'ai rencontré sur plusieurs projets. Entre designers qui éditent visuels, rédacteurs de documentation qui mettent à jour le guide de style et développeurs qui consomment des tokens en production, les modifications simultanées peuvent vite devenir une source de friction. Ici je partage une approche pragmatique, concrète et testée pour maintenir l'harmonie entre ces trois sources.

Comprendre les rôles et la source de vérité

Avant toute chose, je définis clairement les rôles :

  • Figma : l'espace de conception visuelle et prototypes — lieu de validation design.
  • Zeroheight : documentation accessible aux équipes, souvent utilisée par designers et PMs pour la gouvernance des composants.
  • Dépôt (repo) : code source, packages de tokens (npm), et la vérité consommée en production par les développeurs.

    • Dans mon workflow, il faut une source de vérité unique. Je privilégie le repo comme source de vérité finale — ce qui permet de versionner, d'appliquer CI, de publier des packages et de tracer l'historique. Figma et Zeroheight deviennent des interfaces d'édition et de documentation reliées au repo via des pipelines automatisés.

    Choisir les bons outils

    Une bonne boîte à outils est essentielle pour automatiser et réduire les erreurs humaines :

  • Figma Tokens (plugin) ou Tokens Studio — pour exporter les tokens depuis Figma.
  • Style Dictionary ou Theo — transformer tokens JSON en variables CSS/SCSS, JS, Swift, etc.
  • Zeroheight — pour la documentation, peut être alimenté via API ou fichiers JSON.
  • Git avec un workflow GitFlow léger ou trunk-based, plus des hooks (Husky) pour préventer les erreurs.
  • CI/CD (GitHub Actions, GitLab CI) pour valider, tester et publier les tokens sous forme de package (npm, pnpm).

    • Structure des tokens dans le repo

    Je structure toujours les tokens dans un dossier dédié, par exemple /tokens, avec un schéma clair :

  • /tokens/design-tokens.json — format canonical (source de vérité machine-readable)
  • /tokens/metadata.json — informations de version, auteur, changelog minimal
  • /tokens/build/ — sorties générées par Style Dictionary

    • Utiliser un schéma standard (comme JSON Schema pour valider les tokens) aide à détecter les erreurs avant qu'elles n'arrivent en production.

    Workflow recommandé : éditer → valider → publier

    Voici le workflow que j'applique pour éviter les conflits :

  • 1) Édition principale dans Figma : les designers modifient les tokens via le plugin. Le plugin exporte un fichier JSON structurel.
  • 2) PR automatisée : l'export est poussé (manuellement ou via script) vers une branche du repo qui déclenche une CI.
  • 3) Validation CI : la pipeline exécute des checks — validation JSON Schema, tests de régression visuelle si nécessaire, génération via Style Dictionary, lint des tokens.
  • 4) Revue humaine : PR est revue par un développeur ou un responsable design-system. Si approuvé, merge dans main/master.
  • 5) Publication : fusion déclenche publication automatique d'un package (version sémantique) et mise à jour des assets dans Zeroheight via un script ou l'API.

    • Ce flux évite que des modifications directes dans le repo se retrouvent en conflit avec des sources externes car tout passe par des PR et CI.

    Stratégies pour éviter les conflits Git

    Les conflits les plus courants viennent de merges concurrentiels sur le même fichier JSON. J'utilise plusieurs tactiques pour les minimiser :

  • Modulariser les tokens : séparer tokens par catégories (colors.json, spacing.json, typography.json). Les PRs qui touchent une seule catégorie réduisent fortement les conflits.
  • Locking logique : pour des changements majeurs, utiliser une convention de branche (par exemple feature/tokens/) et annoncer la modification dans Slack/Confluence pour que tout le monde évite d'éditer la même catégorie simultanément.
  • Merge par PR et revues obligatoires : interdiction de pousser directement sur main. Les PRs forcent le dialogue et évitent les merges automatiques risqués.
  • Pre-merge auto-resolve minimal : configurer CI pour exécuter un script de merge "tokens" qui normalise le JSON (tri des clefs, formatage) avant merge. Cela réduit les faux conflits provoqués par l'ordre des clefs.
  • Utiliser des patches plutôt que remplacer : le plugin Figma ou scripts d'export peuvent générer des diffs partiels (change-sets) au lieu de remplacer tout le fichier. Appliquer un patch (jq, json-merge) permet des merges plus propres.

    • Automation entre Figma, Zeroheight et le repo

    J'automatise deux flux principaux :

  • Figma → Repo : le plugin exporte des JSONs. Je pousse ces exports sur une branche tokens/export via un script (ou webhooks). CI valide et propose une PR si tout passe.
  • Repo → Zeroheight : après merge, un job CI publie les fichiers JSON transformés vers Zeroheight via leur API (ou génère du markdown/inclusions) pour mettre à jour la documentation automatiquement.

    • Exemple de tâches CI :

  • Lint tokens (json-schema)
  • Génération dans différents formats via Style Dictionary
  • Tests simples (valeurs attendues, pas de couleurs invalides)
  • Publication sur npm + mise à jour de Zeroheight

    • Versioning et compatibilité

    Pour minimiser les ruptures côté développeur, j'utilise le versioning sémantique :

  • patch : corrections non cassantes (orthographe, alias)
  • minor : ajout de tokens (nouvelles couleurs, espacements) compatibles
  • major : breaking changes (changement d'échelle, renommage)

    • Chaque release s'accompagne d'un CHANGELOG automatisé (via Conventional Commits ou commitizen) indiquant les impacts pour les devs. En cas de breaking change, on publie une RFC dans Zeroheight et on planifie la migration.

    Bonnes pratiques pour la collaboration quotidienne

  • Mettre en place des templates de PR pour tokens, demandant : raison du changement, capture d'écran Figma, impact attendu, tests réalisés.
  • Ajouter des pre-commit hooks (Husky) pour valider le formatage et empêcher les commits bruts.
  • Documenter le process dans Zeroheight : où éditer, comment exporter, comment faire une PR.
  • Former rapidement designers et devs à utiliser le plugin Figma Tokens et à comprendre le lifecycle des tokens.

    • Cas concret : éviter un conflit sur colors.json

    Sur un projet récent, deux équipes ont modifié colors.json en même temps : une pour ajuster une nuance, l'autre pour ajouter une famille de couleurs. Le conflit venait d'un remplacement complet du fichier par le plugin.

    J'ai appliqué ces corrections :

  • Diviser colors.json en core-colors.json et brand-colors.json.
  • Modifier le plugin pour exporter en mode patch — j'utilise un script qui fusionne les exports en faisant un smart-merge (fusion par clef, pas remplacement complet).
  • Introduire un pré-check CI qui rejette les PRs si un autre changement sur la même catégorie est en cours (en regardant les branches ouvertes).

    • Résultat : les conflits ont pratiquement disparu et le temps de revue a significativement diminué.

    Outils et snippets utiles

    Quelques commandes/snippets que j'utilise :

  • Validation JSON Schema (CI) : ajouter une étape qui exécute ajv-cli --validate --schema schema.json --data tokens/*.json
  • Tri des clefs avant commit : jq -S '.' tokens/*.json > tmp && mv tmp tokens/*.json (dans un hook pre-commit)
  • Style Dictionary build : style-dictionary build dans la CI pour générer outputs

    • Les plugins et services évoluent vite : garder un œil sur les mises à jour de Figma Tokens, Style Dictionary et l'API Zeroheight vous évitera des surprises.

    Si vous voulez, je peux vous fournir un exemple de pipeline GitHub Actions prêt à l'emploi pour automatiser l'ensemble (export Figma → PR → validation → publication Zeroheight). Dites-moi quelles technologies vous utilisez côté dev (npm, yarn, pnpm, monorepo ou multi-repo) et j'adapte le workflow.