# Design tokens Figma vers theme.json : automatiser la synchronisation

> Exporter les variables Figma en JSON et générer automatiquement les presets de couleurs, d'espacements et de typographie de theme.json, sans recopie manuelle.

- Auteur : Clément Hadrot
- Publié le : 2025-07-11
- Mis à jour le : 2025-07-11
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/design-tokens-figma-theme-json-sync/

## L’essentiel

- Les variables Figma s'exportent en JSON via l'API ou un plugin dédié
- Un script Node convertit ce JSON au format de presets attendu par theme.json
- La synchronisation évite les écarts entre maquette et thème en production

Sur un projet avec un studio de design externe qui itérait régulièrement sur la charte graphique, la recopie manuelle des couleurs et espacements Figma vers le `theme.json` du thème était devenue une source d'erreurs récurrente : un espacement arrondi différemment, une couleur recopiée depuis un ancien export de la maquette plutôt que la version courante. Nous avons mis en place un script qui automatise cette synchronisation, directement à partir des variables Figma exportées.

Ce guide ne couvre pas la conception graphique elle-même dans Figma, seulement la chaîne technique qui relie les variables du fichier de design au fichier de configuration du thème.

## Étape 1 : structurer les variables côté Figma

Le studio de design a organisé ses variables Figma en collections nommées explicitement : `couleurs`, `espacements`, `typographie`, avec des noms de variables qui reprennent directement les slugs attendus côté WordPress (`accent`, `contraste`, plutôt que des noms internes au design comme « Bleu 500 »). Cet alignement de nommage en amont évite toute table de correspondance manuelle supplémentaire dans le script.

## Étape 2 : exporter les variables au format JSON

Figma propose une API REST permettant de récupérer les variables d'un fichier, ou à défaut un export via un plugin dédié au format proche de la spécification W3C des design tokens. Le résultat brut ressemble à ceci :

```
{
  "couleurs": {
    "accent": { "value": "#1d4ed8", "type": "color" },
    "contraste": { "value": "#0f172a", "type": "color" }
  },
  "espacements": {
    "petit": { "value": "8", "type": "number" },
    "moyen": { "value": "16", "type": "number" },
    "grand": { "value": "32", "type": "number" }
  }
}
```

## Étape 3 : écrire le script de conversion

Un script Node.js, exécuté à chaque nouvel export, transforme ce JSON brut au format de presets attendu par `theme.json` :

```
const fs = require('fs');
const tokens = JSON.parse(fs.readFileSync('tokens-figma.json', 'utf8'));

const palette = Object.entries(tokens.couleurs).map(([slug, token]) => ({
  slug,
  color: token.value,
  name: slug.charAt(0).toUpperCase() + slug.slice(1),
}));

const spacingSizes = Object.entries(tokens.espacements).map(([slug, token]) => ({
  slug,
  size: `${token.value}px`,
  name: slug.charAt(0).toUpperCase() + slug.slice(1),
}));

const themeJson = JSON.parse(fs.readFileSync('theme.json', 'utf8'));
themeJson.settings.color.palette = palette;
themeJson.settings.spacing.spacingSizes = spacingSizes;

fs.writeFileSync('theme.json', JSON.stringify(themeJson, null, 2));
```

> L'essentiel à retenir : Les variables Figma s'exportent en JSON via l'API ou un plugin dédié ; Un script Node convertit ce JSON au format de presets attendu par theme.json ; La synchronisation évite les écarts entre maquette et thème en production

Le script préserve intentionnellement le reste du fichier `theme.json` — réglages structurels, styles d'éléments — et ne réécrit que les sections de presets directement issues de Figma, pour éviter d'écraser des réglages qui ne relèvent pas du design system.

## Étape 4 : intégrer la synchronisation au flux de travail

Sur ce projet, la synchronisation reste déclenchée manuellement par un développeur après validation d'une nouvelle itération de charte par le studio de design — nous avons délibérément écarté une automatisation totale à chaque modification Figma, pour garder un point de contrôle humain avant qu'une variable changée par erreur ne se propage en production.

| Approche | Avantage | Risque |
| --- | --- | --- |
| Synchronisation manuelle déclenchée | Contrôle humain avant mise en production | Dépend de la discipline de l'équipe |
| Synchronisation automatique à chaque changement | Aucun décalage possible | Une erreur de manipulation se propage immédiatement |

## Un cas rencontré : un espacement mal typé

Lors d'une première itération, une variable d'espacement exportée par Figma contenait la valeur `16px` déjà suffixée, alors que le script attendait un nombre brut. Le concaténation produisait un absurde `16pxpx`, silencieusement accepté par le fichier JSON mais provoquant un espacement nul dans le rendu réel. Depuis, le script valide chaque valeur numérique avec une expression régulière avant conversion, et interrompt l'exécution avec un message explicite en cas de format inattendu plutôt que de produire une valeur invalide silencieuse.

> Un script de synchronisation qui échoue bruyamment sur une donnée inattendue vaut toujours mieux qu'un script tolérant qui produit un theme.json invalide sans prévenir personne. Le coût d'un blocage visible reste bien inférieur à celui d'une régression silencieuse découverte en production.

## Résultat sur la durée du projet

Sur les six mois du projet, cette automatisation a évité trois épisodes de décalage entre maquette validée et thème en production, pour un temps de mise en place initiale d'environ une journée de développement. Le gain estimé à chaque itération de charte se situe autour de 45 minutes de recopie manuelle évitées, sans compter le temps de débogage qu'aurait coûté un écart passé inaperçu.

## En résumé

Automatiser la conversion des variables Figma vers `theme.json` réduit fortement le risque d'écart entre la maquette validée et le thème livré, à condition de garder un point de contrôle humain avant la mise en production et de valider strictement le format de chaque valeur exportée avant de l'injecter dans le fichier de configuration.