Design tokens vs variables CSS : quelle différence ?

Deux fichiers sont ouverts côte à côte. tokens.json dit "brand-600": { "$value": "#2563eb", "$type": "color" } ; variables.css dit --color-brand-600: #2563eb;. Même valeur, presque le même nom — et la question naturelle est de savoir lequel vous êtes censé écrire.

La réponse : ce ne sont pas des concurrents, ce sont la source et la sortie. Les design tokens sont la source — des décisions de design stockées dans un fichier neutre par rapport aux outils. Les propriétés personnalisées CSS sont un export — les mêmes décisions rendues pour les navigateurs. Une analogie utile vient des compilateurs, et c’est bien une analogie : le fichier de tokens est le code source, la feuille de style est une cible de compilation, et les Figma Variables ou les ressources natives sont des cibles sœurs générées à partir de la même source. La distinction paraît académique et ne l’est pas ; elle détermine ce qui peut consommer vos décisions, ce que l’outillage peut vérifier, et qui révise quoi. Le versant source est couvert dans notre guide des design tokens — cet article porte sur la frontière elle-même.

Qu’est-ce que les tokens atteignent que les variables CSS ne peuvent pas ?

Les environnements non-navigateur. Une propriété personnalisée est une fonctionnalité CSS : elle atteint tout ce qu’une feuille de style atteint, et rien d’autre. Les décisions dans un produit vont plus loin — le même bleu et le même espacement doivent tenir dans le fichier Figma, les applications iOS et Android, les modèles d’e-mail, la présentation que l’équipe commerciale exporte. Si variables.css est la source de vérité, chacun de ces consommateurs est alimenté par transcription manuelle, et les copies faites à la main dérivent.

Un fichier de tokens les alimente tous sous forme de vues générées : propriétés personnalisées pour le web, Figma Variables pour le design, ressources de plateforme pour le natif. Le jour où un deuxième consommateur apparaît est le jour où la différence cesse d’être théorique — avec un seul consommateur, les deux approches sont quasi indiscernables ; avec deux, une seule d’entre elles possède une source.

Que sait un fichier de tokens qu’une feuille de style ignore ?

Le sens. Pour CSS, --brand-600 est une valeur non typée qui est substituée là où elle est utilisée ; rien dans le langage ne sait que c’est une couleur, et une faute de frappe à l’intérieur échoue silencieusement au moment de l’emploi. Un fichier de tokens en sait plus : $type indique que la valeur est une couleur, $description dit à quoi elle sert, et une référence enregistre qu’accent est défini comme {color.brand.600} plutôt que d’y être égal par coïncidence.

C’est de cette connaissance que se nourrit l’outillage. Une compilation peut valider le fichier — rejeter une couleur mal formée ou une référence à un token qui n’existe pas — avant toute mise en production. La documentation peut être générée au lieu d’être écrite. Les transformations peuvent être appliquées mécaniquement : px vers rem, hex vers OKLCH, une seule source rendue selon les conventions de chaque cible. Rien de tout cela n’est accessible à une feuille de style nue, parce que la feuille de style stocke des réponses sans leurs questions.

Comment un token devient-il une variable CSS ?

Mécaniquement. Trois tokens en source DTCG :

{
  "color": {
    "brand": { "600": { "$value": "#2563eb", "$type": "color" } }
  },
  "spacing": {
    "4": { "$value": "23px", "$type": "dimension" }
  },
  "semantic": {
    "accent": { "$value": "{color.brand.600}", "$type": "color" }
  }
}

Et le bloc :root généré à partir d’eux :

:root {
  --color-brand-600: #2563eb;  /* oklch(0.546 0.215 262.9) */
  --spacing-4: 23px;
  --color-accent: var(--color-brand-600);
}

Les noms deviennent des noms de propriété, les valeurs sont reportées, et — le détail qui mérite qu’on le remarque — la référence survit sous forme de var() : l’export préserve la structure de la décision, pas seulement sa réponse du moment. Les composants consomment ensuite la sortie normalement :

.card {
  padding: var(--spacing-4);
  background: var(--color-accent);
}

Voyez la source et les exports côte à côte dans Scale Composer — le fichier DTCG d’un côté et les mêmes noms rendus en propriétés personnalisées CSS, un thème Tailwind v4 et des Figma Variables de l’autre ; modifiez la source et les trois sorties évoluent ensemble.

Les tokens et les variables ont-ils des cycles de vie différents ?

Oui, et la différence apparaît lors de la revue de code. Les tokens sont des décisions de design : ils sont proposés, révisés, versionnés et comparés — une pull request qui fait passer accent d’une primitive à une autre est un changement de design qui prend la forme d’un diff révisable, et designers comme développeurs ont légitimité à commenter. Le variables.css généré est un détail d’implémentation : un artefact de compilation qui est régénéré, pas édité. Éditer à la main une feuille de style générée a la même durée de vie qu’éditer à la main n’importe quelle sortie compilée — jusqu’à la prochaine compilation.

La règle pratique qui en découle : révisez la source, générez la cible, et ne laissez entrer dans la feuille de style aucune valeur qui ne soit pas passée par la source.

Quand les variables CSS seules suffisent-elles honnêtement ?

Quand il n’y a qu’un seul consommateur et qu’il n’y en aura peut-être jamais d’autre. Un produit web mono-plateforme sans transfert vers Figma, maintenu par celles et ceux qui l’ont écrit, perd peu à déclarer ses propriétés personnalisées directement — le fichier est plus simple, la chaîne d’outils plus courte, et un bloc :root discipliné avec des propriétés nommées par rôle capte une grande partie du bénéfice de nommage sans aucune infrastructure de tokens. C’est un choix légitime, pas un choix au rabais.

La couche de tokens justifie son coût quand les consommateurs se multiplient : la première bibliothèque Figma qui doit correspondre au code, la première surface native, le premier deuxième thème. Adopter la machinerie avant cela, c’est payer pour une portée que vous n’utilisez pas encore — raisonnable en guise de préparation, mais pas obligatoire.

Qu’apportent les variables CSS à l’exécution ?

Une chose que les tokens seuls ne peuvent pas : la ré-résolution en direct dans le navigateur. Les propriétés personnalisées se résolvent via la cascade — les mécanismes sont documentés dans le guide de MDN sur les propriétés personnalisées CSS — si bien que les re-déclarer sous une portée bascule tous les consommateurs d’un coup, sans rien recompiler :

[data-theme="dark"] {
  --color-accent: oklch(0.70 0.14 262.9);  /* valeur sombre re-dérivée */
}

Chaque var(--color-accent) de la page se re-résout à l’instant où l’attribut arrive. C’est une propriété du format de sortie, pas de la source — une raison pour laquelle l’export CSS est la bonne cible même quand les tokens sont la source, et le mécanisme sur lequel reposent les systèmes de thème. Quelles valeurs le mode sombre doit contenir est un sujet à part entière ; ici, il suffit que la bascule coûte un seul bloc de déclaration.

Générez vos variables à partir d’une source

La frontière est la plus nette quand vous la franchissez délibérément. Exportez des propriétés personnalisées CSS depuis une source de tokens — changez une décision du côté source (une couleur de départ, un pas d’échelle), ré-exportez, et lisez le diff du côté CSS : les variables se mettent à jour, la structure de références tient, et rien n’a eu besoin d’être édité à la main.