Les Variables Figma sont arrivées en 2023 comme la réponse tant attendue de la plateforme aux tokens de design. La fonctionnalité est puissante : des collections nommées de valeurs primitives — couleurs, nombres, chaînes, booléens — que vous pouvez lier à n'importe quelle propriété de n'importe quel composant. Modifiez la variable, chaque instance se met à jour. Ajoutez une collection mode sombre, chaque liaison de variable s'échange automatiquement.

Pour la génération de code IA, les Variables ne sont pas seulement utiles. Elles sont le mécanisme qui convertit un fichier Figma d'une maquette pixel-parfaite en une spec que votre agent peut implémenter correctement. Quand une couleur a un nom — color/brand/primary, pas #7F5CFE — l'agent peut la mapper à un token de code, implémenter correctement le mode sombre, et produire une sortie qui participe à votre design system réel.

Voici le problème : la plupart des fichiers Figma en usage actif aujourd'hui n'ont pas de Variables configurées. figmascope gère les deux cas. Cet article explique comment.

Ce que sont réellement les Variables

Une Variable Figma est un scalaire nommé lié à une collection. Les collections organisent les variables par mode — « Light » et « Dark » sont l'exemple canonique. Chaque variable d'une collection peut avoir des valeurs différentes par mode : color/surface/background est #FFFFFF en Light et #0D0D0D en Dark. La liaison se propage : chaque remplissage qui référence color/surface/background se met à jour quand vous changez de mode.

Les Variables peuvent être des couleurs, des nombres, des chaînes ou des booléens. En pratique, les plus impactantes sont les couleurs et les nombres — ce qui couvre la plupart de la surface des tokens dans un design system typique : palette de couleurs, échelle d'espacement, rayons de bordure, tailles de police, valeurs d'élévation.

Figma expose les Variables via son API REST comme une collection localVariables. Chaque variable a un ID, un nom, un type, et des valeurs par mode. Les propriétés de composants qui référencent des variables portent un champ boundVariables avec l'ID de la variable. Ce sont des données structurées qui transitent proprement dans le pipeline d'extraction.

Le chemin heureux : les Variables sont présentes

Quand un fichier Figma a des Variables, figmascope les lit depuis l'API et construit un tokens.json suivant une structure compatible avec le groupe communautaire W3C Design Tokens. Chaque token a un $value et un $type. Les tokens de couleur obtiennent des valeurs hex avec alpha optionnel. Les tokens d'espacement obtiennent des valeurs numériques avec un indicateur d'unité px. Le nom du token suit le chemin de collection et de nom de la variable :

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

Quand l'IR par écran est construit, chaque remplissage qui avait une référence boundVariables reçoit le nom du token au lieu du hex résolu. Le nœud porte :

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

Pas #7F5CFE. Le nom du token. L'agent lit ceci et génère background-color: var(--color-brand-primary) ou Color.brandPrimary ou quel que soit le modèle de consommation des tokens du framework cible. C'est la sortie que vous voulez : du code connecté à votre design system, pas du code qui cassera au moment où un designer met à jour une couleur.

Le nommage sémantique est la différence entre du code qui vieillit bien et du code qui dérive. Une valeur hex dans le source est un passif ; une référence à un token est un contrat. Les Variables sont ce qui rend les fichiers Figma capables d'exprimer des contrats, pas seulement des pixels.

La réalité : la plupart des fichiers n'ont pas de Variables

Les Variables nécessitent le plan Figma Professional ou supérieur. Elles nécessitent un designer qui les a configurées — ce qui signifie créer des collections, nommer des variables, et les lier manuellement à chaque propriété de composant. Sur un fichier de design system mature et bien maintenu, c'est fait. Sur le Figma produit d'une startup, un fichier client d'un freelance, ou tout fichier qui date d'avant la fonctionnalité Variables, c'est généralement non.

figmascope a été conçu pour être utile pour ces fichiers aussi. Il dégrade gracieusement : quand les Variables sont absentes, il revient à l'inférence de tokens basée sur la fréquence.

Le repli : inféré-depuis-la-fréquence

L'algorithme d'inférence fonctionne ainsi :

  1. Parcourir chaque nœud feuille dans chaque frame exporté.
  2. Collecter toutes les couleurs de remplissage, valeurs d'espacement et rayons de bordure.
  3. Compter les occurrences de chaque valeur unique.
  4. Les valeurs qui apparaissent au-dessus d'un seuil de fréquence sont promues en tokens inférés.
  5. Chaque token reçoit un nom dérivé de la valeur : color.7f5cfe, spacing.16, radius.8.

Le tokens.json de sortie ressemble structurellement au chemin Variables, mais les noms sont dérivés des valeurs plutôt que sémantiques :

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

Dans l'IR, les nœuds qui utilisent ces valeurs obtiennent des références de tokens : "tokenRef": "color.7f5cfe". Pas des littéraux codés en dur. Des références — juste vers des tokens inférés plutôt que nommés.

L'agent génère quand même du code référencé par tokens. var(--color-7f5cfe) n'est pas aussi lisible que var(--color-brand-primary), mais c'est quand même un token — vous pouvez le trouver-et-remplacer, le renommer, auditer son utilisation. C'est un handle nommé sur une valeur, pas un nombre magique.

Le champ tokensSource

Chaque bundle figmascope inclut un _meta.json qui documente ce qu'il contient et comment il a été produit. Le champ tokensSource a trois valeurs possibles :

Cela importe car cela indique à l'agent consommateur (et au développeur qui lit le bundle) dans quelle mesure faire confiance aux noms de tokens. Un bundle figma-variables est la source de vérité pour votre design system. Un bundle inferred-from-frequency est un échafaudage structurel utile qui nécessite une révision de nommage par le designer avant d'être canonique. Un bundle none est un point de départ avec des valeurs codées en dur qui doivent être tokenisées ultérieurement.

Les métadonnées honnêtes sont sous-estimées. Les outils qui infèrent silencieusement sans le signaler créent une fausse confiance. figmascope expose explicitement la chaîne d'inférence pour que vous sachiez ce avec quoi vous travaillez.

Pourquoi l'inférence par fréquence vaut mieux que rien

L'alternative à l'inférence par fréquence est d'émettre des valeurs littérales résolues partout — #7F5CFE dans chaque nœud de remplissage qui utilise cette couleur. Cela produit du code plus difficile à refactoriser, plus difficile à auditer, et plus difficile à connecter à un design system quand il en est finalement ajouté un.

L'inférence par fréquence extrait au minimum l'ensemble des valeurs que le design utilise réellement. Si #7F5CFE apparaît 47 fois dans le design, c'est un signal : c'est une couleur primaire, pas un accent. Le nom du token ne le sait pas — c'est juste color.7f5cfe — mais les données de fréquence racontent l'histoire. Un agent auquel on donne les tokens inférés peut faire des suppositions raisonnables sur quelles valeurs sont primaires et lesquelles sont uniques.

Plus pratiquement : l'inférence par fréquence vous donne un tokens.json différentiable entre les versions. Si vous exportez le même fichier deux fois après qu'un designer ait changé une couleur récurrente, le diff montre que la valeur du token a changé. Sans inférence, vous traceriez chaque changement littéral individuel éparpillé dans plusieurs fichiers IR.

Ce que les designers devraient quand même faire

L'inférence par fréquence est une couche de compatibilité, pas un substitut aux Variables. Le bon chemin est que les designers adoptent les Variables pour toutes les valeurs qui participent à un design system : couleurs de marque, échelle neutre, échelle d'espacement, rayons de bordure, élévation, typographie. Une fois celles-là en place, le bundle figmascope passe de tokens de qualité échafaudage à des tokens de qualité production.

Les Variables débloquent également le thèming dans le bundle : plusieurs valeurs de mode par token. Un fichier avec des modes Light/Dark produit un tokens.json avec des valeurs par mode qui s'alimente directement dans des propriétés CSS custom avec des surcharges de media query, ou dans des objets de thème spécifiques à la plateforme. C'est impossible à inférer depuis un instantané de design unique — cela nécessite une intention explicite du designer, exprimée via les Variables.

Le chemin de mise à niveau est incrémental. Une équipe peut commencer avec des tokens de qualité inférence aujourd'hui, adopter les Variables progressivement à mesure que le design system mûrit, et obtenir automatiquement de meilleurs bundles en le faisant. Le champ tokensSource trace où vous en êtes dans cette progression.

Le pipeline de tokens en entier

Pour le rendre concret, voici l'ordre de résolution complet que figmascope utilise pour chaque remplissage dans l'IR :

  1. Le nœud a-t-il une référence boundVariables.fills ? Si oui, résoudre vers le nom de la variable et la valeur du mode zéro. Source de token : figma-variables.
  2. La valeur résolue est-elle présente dans les tokens de fréquence inférés (au-dessus du seuil) ? Si oui, mapper vers le nom du token inféré. Source de token : inferred-from-frequency.
  3. Sinon : utiliser directement la valeur hex résolue. Pas de référence de token. Source de token : none.

Les étapes sont essayées dans l'ordre. La source de meilleure qualité l'emporte. Le champ tokensSource dans _meta.json reflète le chemin dominant pour l'ensemble du bundle.

Cela signifie qu'un fichier partiellement configuré avec Variables — où certains composants ont des liaisons et d'autres non — produit un bundle mixte. Tokens nommés là où ils existent, tokens inférés là où ils n'existent pas. C'est le bon comportement : utiliser chaque parcelle d'information structurée disponible, dégrader gracieusement là où elle manque, et être honnête sur le chemin emprunté par chaque valeur.

Exportez votre bundle depuis l'application figmascope pour voir quel tokensSource votre fichier produit. Utilisez ensuite le bundle avec Claude Code ou Cursor pour une génération de code précise, référencée par des tokens.