Architecture des variables Figma : comment construire un système de tokens qui survit à la production

La plupart des équipes qui utilisent les variables Figma construisent sur un modèle mental hérité des styles, et c'est là le problème. Des variables sans architecture, ce sont juste des styles avec des clics en plus.

Les équipes qui s'en sortent traitent les variables Figma comme une vraie couche de design tokens : structurée, aliasée, scopée et exportable. Celles qui se plantent sont à une demande de dark mode d'une reconstruction complète. Voici l'architecture qui survit à la production.

Les variables ne sont pas des styles, elles sont la couche de tokens

Les styles Figma sont des préréglages. Vous définissez une couleur, un style de texte, un effet, et vous l'appliquez directement à un calque. Ça marche pour un fichier mono-marque, mono-mode, sans exigence de handoff développeur. Ça cesse de marcher dès que quoi que ce soit change.

Les variables Figma sont des tokens. Une variable porte une valeur, mais elle peut aussi porter une référence vers une autre variable. Cette chaîne de références, et la possibilité de basculer des ensembles entiers de valeurs résolues via les modes, est ce qui rend les variables architecturalement différentes des styles. La distinction n'a rien de cosmétique. C'est la différence entre un système de préréglages et un système de tokens.

L'architecture de tokens en trois couches

Primitives, sémantique, composant. Tout système de variables qui fonctionne a ces trois couches. Sauter la couche sémantique est l'erreur d'architecture la plus courante dans les fichiers Figma aujourd'hui.

Les trois couches correspondent à trois rôles : les primitives portent les valeurs brutes, les tokens sémantiques portent le sens, et les tokens de composant se limitent à une seule famille de composants. Chaque couche ne parle qu'à celle du dessous. Pas de saut, pas de raccourci.

Les trois couches ne sont pas optionnelles selon la taille du projet. Un petit système de cinq composants a quand même besoin des trois couches, sinon la première demande de thème le fait exploser.

Couche un : les primitives

Les primitives sont les valeurs brutes. blue-500, gray-900, space-4, radius-md. C'est la palette, l'échelle, la fondation. Elles ne sont jamais attachées directement à une couche de composant.

Le rôle d'une primitive : exister, être aliasée depuis le dessus et rester discrète. Si un designer va chercher blue-500 pour l'appliquer à un bouton, l'architecture est déjà cassée. Les primitives appartiennent à la collection des primitives et nulle part ailleurs.

La convention de nommage compte ici. Les primitives doivent suivre une échelle ou une palette, jamais le sens. blue-500 est correct. button-blue comme primitive est une erreur de catégorie qui fait mal à l'échelle.

Couche deux : la sémantique

Les tokens sémantiques portent le sens. surface, surface-elevated, text-primary, text-muted, border-default, border-focus. Ils répondent à « à quoi sert cette couleur ? » plutôt qu'à « quelle est cette couleur ? »

Les tokens sémantiques s'aliasent vers des primitives. C'est leur seule relation. L'aliasing sémantique vers sémantique crée de l'ambiguïté sur l'endroit où vit la valeur et rend les surcharges de mode peu fiables.

Cette couche est celle où vivent vos modes clair, sombre et marque. Un token sémantique se résout vers une primitive différente selon le mode actif, c'est ainsi que le theming fonctionne vraiment. La primitive blue-500 ne change pas. Le token sémantique text-link change ce vers quoi il se résout selon le mode.

Couche trois : le composant

Les tokens de composant se limitent à une seule famille de composants. button-bg, button-text, button-border, card-surface, card-border, input-bg. Ils s'aliasent vers des tokens sémantiques, jamais vers des primitives.

Le rôle d'un token de composant : la spécificité sans couplage. button-bg se résout vers surface-action, qui se résout vers blue-500. Quand la marque change, vous mettez à jour la couche sémantique et le bouton suit. Le token de composant n'est pas touché.

Une objection courante : ça fait des tokens en plus pour rien. La raison, c'est que button-bg et surface-action peuvent diverger. À un moment, une décision produit exigera que le bouton utilise une surface légèrement différente. Les tokens de composant vous donnent le point de surcharge sans toucher au système sémantique.

Modes contre collections : l'arbre de décision

Les modes font basculer des valeurs à l'intérieur d'une collection. Les collections séparent les préoccupations. Ce n'est pas la même chose, et les confondre est la source de la plupart des confusions d'architecture dans les setups de variables Figma.

La règle : une collection par préoccupation, des modes pour les variantes d'une même préoccupation. La couleur est une préoccupation. L'espacement en est une autre. Clair et sombre ne sont pas des préoccupations distinctes. Ce sont des modes de la même préoccupation couleur.

Quand utiliser un mode plutôt qu'une nouvelle collection :

• Une valeur différente de la même chose ? Mode.
• Une chose entièrement différente ? Collection.
• Basculer entre clair et sombre ? Un mode dans la collection couleur.
• Basculer entre espacement compact et confortable ? Un mode dans la collection espacement.
• Ajouter une marque ? Un mode dans la couche sémantique, pas une nouvelle collection.

Les quatre règles de scoping

Le scoping des variables contrôle où une variable peut être appliquée dans Figma. Se tromper ici, c'est laisser les designers attraper des primitives au lieu de tokens sémantiques, et la discipline d'architecture s'effondre au moment de l'usage.

Les quatre règles sont non négociables :

1. Scopez les primitives sur aucun. Les primitives ne doivent être applicables nulle part. Ce sont des valeurs internes, pas des tokens destinés aux consommateurs. Cachez-les complètement du menu d'application.
2. Scopez les tokens sémantiques à leur type. Un token sémantique de couleur est scopé aux fills et strokes. Un token d'espacement est scopé aux champs de gap, padding et taille. Gardez un scope serré.
3. Scopez les tokens de composant à leur famille. Un token de bouton ne doit pas être applicable à une carte. Si le scope est trop large, la frontière du composant ne veut plus rien dire.
4. N'exposez jamais les primitives aux consommateurs. Si un designer ou un développeur applique une primitive à un calque, le système a échoué au niveau du scoping. C'est un échec de process, pas un échec d'utilisateur.

La chaîne d'alias qui rend les thèmes possibles

Un thème qui fonctionne est une chaîne d'alias : le composant s'aliase vers le sémantique, le sémantique vers la primitive, la primitive porte la valeur. La longueur de la chaîne est de trois, toujours trois.

Une chaîne de deux (composant vers primitive) saute la couche de traduction et rend les modes impossibles sans surcharges manuelles sur chaque token de composant. Une chaîne de quatre crée de l'ambiguïté sur la couche sémantique qui porte le mode, et l'auditer devient un exercice de débogage plutôt qu'une simple consultation.

button-bg → surface-action → blue-500 → #0066FF

Copy

Cette chaîne survit au dark mode en mettant à jour surface-action pour pointer vers blue-300 dans le mode sombre de la collection sémantique. Le token button-bg se met à jour automatiquement. La primitive blue-500 se résout toujours vers #0066FF. Rien d'autre n'a besoin de changer.

Modes clair, sombre et marque

Les trois modes dont la plupart des systèmes de variables ont besoin sont clair, sombre et marque. Seule la couche sémantique les porte. Jamais la couche primitive.

Appliquer des modes aux primitives est une erreur de catégorie. blue-500 vaut toujours #0066FF. C'est une primitive. Elle n'a pas de variante claire ou sombre parce qu'elle ne porte aucun sens. Le token sémantique text-link a une variante claire et une sombre parce qu'il porte un sens qui se résout différemment selon les contextes.

Les modes de marque fonctionnent de la même façon. Une seconde marque n'a pas besoin d'une seconde palette de primitives, sauf si elle utilise des valeurs brutes réellement différentes. La plupart du temps, un mode de marque dans la couche sémantique qui pointe vers un autre sous-ensemble de primitives existantes est le bon choix. Deux collections de primitives complètes pour deux marques, c'est généralement trop. Pour voir comment les décisions de couleur en amont structurent tout ça, l'article sur le système de couleurs du dark mode vaut la lecture avant de figer la structure de votre couche sémantique.

Variables de type nombre, string et booléen

Les variables Figma ne sont pas que des couleurs. Les variables numériques contrôlent l'espacement, les tailles et les rayons. Les variables string contrôlent le texte dans les fichiers de design. Les variables booléennes contrôlent la visibilité des calques, ce qui correspond directement aux props de composant.

C'est la partie du système de variables que la plupart des équipes n'utilisent pas, et c'est celle qui comble le plus spectaculairement l'écart entre design et code. Une échelle d'espacement définie en variables numériques et appliquée aux gaps d'auto-layout signifie qu'un changement dans la variable met à jour chaque composant utilisant ce token. C'est ce que fait un vrai système de tokens.

Les variables string avec modes de locale permettent aux designers de basculer un fichier entre anglais et arabe et de voir la mise en page casser en temps réel. Les variables booléennes mappées sur les props de composant donnent au composant Figma et au composant de code une relation de props un pour un, ce qui rend le handoff développeur vérifiable plutôt qu'interprétable.

Handoff vers le code : le schéma qui marche

Un système de variables ne vaut que par son export. Le schéma de handoff qui fonctionne combine Tokens Studio ou l'API REST des variables Figma, un pipeline de transformation et un script d'import côté code.

Tokens Studio exporte les collections de variables dans un format JSON structuré compatible avec Style Dictionary. Style Dictionary transforme ce JSON vers la sortie dont le codebase a besoin : propriétés CSS custom, color sets Swift, fichiers de ressources Kotlin, config Tailwind. L'étape de transformation est celle où les conventions de nommage sont normalisées et où tout nommage propre à Figma qui ne correspond pas aux conventions du code est nettoyé.

Le pipeline doit tourner à chaque mise à jour de variable, pas manuellement. Une GitHub Action déclenchée par un push Tokens Studio, ou un webhook Figma qui se déclenche sur les changements de variables, garde les tokens côté code synchronisés sans que personne n'ait à penser à exporter. C'est le schéma que Stripe et Atlassian font tourner à grande échelle, et il est faisable dans tout codebase qui a une étape de build. Pour les choix de format des tokens de couleur en sortie, OKLCH color vaut la lecture avant de figer vos valeurs de propriétés CSS custom.

---

Vous voulez un système de variables Figma qui survit aux modes, aux marques et au handoff développeur sans réécriture ? Brainy conçoit des architectures de tokens de production dans Figma avec le modèle en trois couches, la chaîne d'alias et le pipeline d'export qui s'intègre proprement à votre codebase. Engagez Brainy

---

Sept erreurs courantes qui cassent les systèmes de variables

La plupart de ces erreurs ont une cause commune : traiter le panneau des variables comme un meilleur panneau de styles au lieu d'une couche d'architecture. Le changement de modèle mental est la solution. Tout le reste en découle.

L'audit du système de variables

Lancez cet audit sur n'importe quel système de variables Figma et vous repérerez la dette d'architecture avant qu'elle ne parte en production.

Structure

• Trois collections minimum : primitives, sémantique, composant (ou nommage équivalent)
• Chaque collection a une seule préoccupation claire
• Aucune collection ne mélange les types (couleur et espacement dans la même collection, c'est un échec)

Chaîne d'alias

• Chaque token de composant s'aliase vers un token sémantique, pas une primitive
• Chaque token sémantique s'aliase vers une primitive, pas un autre token sémantique
• Aucun token ne contient de valeur brute sauf les primitives
• La longueur de la chaîne d'alias est exactement de trois pour tous les tokens de couleur

Modes

• Clair et sombre sont des modes de la collection sémantique, pas des collections séparées
• Les variantes de marque sont des modes de la collection sémantique, pas des fichiers séparés
• La collection de primitives n'a aucun mode

Scoping

• Les variables primitives sont scopées sur aucun (applicables nulle part)
• Les variables sémantiques sont scopées à leur type (couleur pour fills/strokes, espacement pour les champs de layout)
• Les variables de composant sont scopées à leur famille de composants

Handoff

• Les variables sont exportables via Tokens Studio ou l'API REST
• Un pipeline de transformation existe et il est automatisé
• Les tokens côté code respectent la convention de nommage des variables Figma, avec des exceptions documentées

Si plus de trois de ces points échouent, le système a besoin d'une reconstruction, pas d'un patch. Une palette de couleurs de marque couvre les décisions de couleur en amont qui alimentent la couche primitive, si c'est là que l'audit révèle le plus de dette.

FAQ

Quelle est la différence entre les variables Figma et les styles Figma ?

Les styles sont des préréglages appliqués directement aux calques. Les variables sont des tokens qui peuvent se référencer entre eux et basculer de valeur via les modes. Les variables font tout ce que font les styles, plus le theming, plus le handoff développeur par export. Pour un nouveau design system, les variables sont le bon choix. Pour un fichier existant avec un système de styles mature, mieux vaut rédiger un plan de migration avant de basculer.

Combien de collections un système de variables Figma doit-il avoir ?

Trois à cinq pour la plupart des systèmes : primitives, sémantique, composant, et éventuellement des collections séparées pour l'espacement et la typographie si ces échelles sont assez complexes pour justifier leurs propres règles de scoping. Plus de cinq collections est généralement le signe que les préoccupations ne sont pas groupées correctement.

Les variables Figma peuvent-elles remplacer Tokens Studio ?

Pour la création et l'édition dans Figma, oui. Le panneau natif des variables gère l'essentiel de ce que Tokens Studio faisait avant la sortie de l'API des variables. Pour l'export et la transformation, Tokens Studio apporte encore de la valeur car il dispose d'un pipeline mature vers Style Dictionary et gère des cas limites que l'export natif ne gère pas. Les deux outils sont complémentaires pour l'instant, pas concurrents.

Que se passe-t-il si j'aliase un token sémantique vers un autre token sémantique ?

La résolution des modes devient ambiguë. Si text-secondary s'aliase vers text-primary et que vous passez en mode sombre, Figma résout la chaîne et peut ne pas appliquer la surcharge du mode sombre là où vous l'attendez. L'aliasing sémantique vers sémantique rend aussi l'audit du système presque impossible à l'échelle. La règle est stricte : les tokens sémantiques s'aliasent uniquement vers des primitives.

Comment gérer une troisième marque sans reconstruire le système ?

Ajoutez un troisième mode à la collection sémantique. La collection de primitives est partagée entre les marques, sauf si elles utilisent des valeurs brutes réellement différentes. Un mode de marque dans la couche sémantique qui pointe vers un autre sous-ensemble de primitives est la bonne architecture. Si les marques sont si différentes que leurs palettes de primitives ne se recoupent pas, deux collections de primitives avec une structure sémantique partagée sont la solution de repli.

Le modèle en trois couches est-il nécessaire pour les petits projets ?

Oui, mais la taille de chaque couche diminue. Un petit projet peut avoir quinze primitives, huit tokens sémantiques et deux tokens de composant par composant. L'architecture reste de trois couches. La tentation de sauter le sémantique sur les petits projets explique pourquoi tant de petits projets deviennent de la dette d'architecture dès l'arrivée d'un second designer ou d'une demande de dark mode. Pour voir où la architecture de tokens se place dans la décision de stack plus large, l'article Framer vs Webflow vs Next.js donne du contexte.

Le changement que les variables Figma débloquent vraiment

Un vrai système de variables dans Figma est ce qui se rapproche le plus d'une source de vérité unique entre design et dev. Pas un document de handoff. Pas un lien Zeplin. Une couche de tokens vivante, exportable et structurée que les deux côtés lisent à partir des mêmes définitions.

Les équipes qui traitent les variables comme de l'architecture réduisent de moitié la dette de leur design system, non pas parce que les variables sont magiques, mais parce que la discipline d'architecture qu'exige un bon système de variables force aussi les décisions que les design systems repoussaient sans cesse. Que signifie ce token ? Vers quoi peut-il s'aliaser ? Qui possède la primitive ? Ces questions ont des réponses maintenant, et les réponses vivent dans le fichier.

Des variables sans architecture, ce sont juste des styles avec des clics en plus. Des variables avec le modèle en trois couches, la chaîne d'alias, les règles de scoping et le pipeline d'export, c'est un design system capable de survivre à une seconde marque, à un dark mode et à un développeur qui n'a jamais ouvert Figma.

Construisez l'architecture, pas seulement les tokens.