Design tokens : le guide pratique en trois niveaux

Qu’est-ce qu’un design token

Un token associe un nom à une valeur : color-brand vaut #272DCB, space-4 vaut 16 px, radius-media vaut 8 px. Les composants lisent le nom, jamais la valeur. Le jour où la valeur change, tout ce qui l’utilise suit, dans Figma comme dans le code.

L’intérêt n’est pas technique. C’est un vocabulaire commun : quand un designer dit « fond discret » et qu’un développeur écrit bg-subtle, ils parlent de la même chose, et cette chose n’existe qu’à un seul endroit.

Le problème des variables à plat

La plupart des projets commencent par une liste : blue-500, blue-600, grey-100, grey-900. Ça tient tant que le produit est petit. Puis viennent les questions sans réponse : le texte secondaire, c’est grey-500 ou grey-600 ? Le bouton prend blue-600 ou brand-primary ? Et le thème sombre, on duplique tout ?

Le problème vient de ce qu’un même nom porte deux informations : la valeur et l’usage. Les trois niveaux les séparent.

Trois niveaux, trois questions

Chaque niveau répond à une seule question. C’est l’organisation utilisée sur ce site, et celle que reprend Material Design avec ses niveaux ref, sys et comp.

• Référence : qu’est-ce qui existe ? La palette, l’échelle d’espacement, les rayons, les polices. Exemple : --ds-ref-color-blue-600. Aucun composant ne lit ce niveau directement.
• Système : à quoi ça sert ? Le fond par défaut, le texte secondaire, la couleur de marque, le rayon d’un média. Exemple : --ds-sys-color-text-muted. C’est le seul niveau qui change avec le thème.
• Composant : qui l’utilise ? Le fond du bouton principal au survol, le rayon d’un badge. Exemple : --ds-comp-button-color-bg-primary-hover, qui pointe vers un token système.

--ds-ref-color-blue-600: #272dcb;
--ds-sys-color-brand: var(--ds-ref-color-blue-600);
--ds-comp-badge-color-text-brand: var(--ds-sys-color-brand);

Pour changer le bleu partout, on touche un token de référence. Pour décider que le texte secondaire devient plus foncé, un token système. Pour retoucher un seul composant, un token composant. Chaque changement a un seul endroit où se faire.

Comment nommer ses tokens

Un bon nom se lit de gauche à droite, du plus général au plus précis : espace de noms, niveau, catégorie, rôle, variante, état.

--{espace}-{niveau}-{catégorie}-{rôle}-{variante}-{état}
--ds-comp-button-color-bg-primary-hover

• Nommez par le rôle, pas par la valeur, dès le niveau système : color-text-muted plutôt que grey-500. Un rôle survit à un changement de palette.
• Gardez l’ordre identique partout. Si la catégorie vient avant le rôle une fois, elle vient avant le rôle tout le temps.
• Évitez les synonymes : choisissez entre « subtle » et « light », entre « default » et « base », et tenez-vous-y.
• Préfixez avec un espace de noms court et propre au projet. Il évite les collisions avec les classes d’un framework : sur ce site, mb- aurait été confondu avec la marge de Tailwind, d’où ds-.

Le thème sombre sans douleur

Avec trois niveaux, un thème sombre se résume à redéfinir les tokens système. Les références ne bougent pas, les composants non plus : ils lisent des rôles, et les rôles changent de valeur.

:root { --ds-sys-color-bg-default: var(--ds-ref-color-neutral-0); }
.dark { --ds-sys-color-bg-default: var(--ds-ref-color-neutral-950); }

Un piège classique : réutiliser la couleur de marque telle quelle en sombre. Un bleu foncé lisible sur blanc devient illisible sur fond noir. Prévoyez une valeur sombre pour chaque rôle de couleur, et vérifiez le contraste (4,5:1 minimum pour du texte).

Du fichier au produit : Figma et le code

• Dans Figma, les variables natives gèrent les références entre elles et les modes (clair, sombre). Une collection par niveau garde la même logique que le code.
• Le format d’échange standard est le JSON du W3C Design Tokens Community Group (DTCG) : chaque token a un $type et une $value, les références s’écrivent {ref.color.blue.600}.
• Style Dictionary transforme ce JSON en CSS, en Swift, en Kotlin ou en ce que vous voulez. Tokens Studio le synchronise avec Figma.
• Avec Tailwind v4, un bloc @theme inline branche les utilitaires (bg-brand, rounded-media) sur vos tokens système : les classes restent courtes, les valeurs restent à un seul endroit.

Les erreurs les plus fréquentes

• Créer des tokens pour chaque valeur existante, au lieu de décider d’abord quelles valeurs garder. Un audit qui trouve treize rayons différents doit finir avec deux ou trois, pas treize tokens.
• Laisser les composants lire les références. Le jour du thème sombre, il faut repasser sur chaque composant.
• Nommer par la valeur au niveau système : color-blue-text. Le jour où la marque devient verte, le nom ment.
• Oublier les états : survol, focus, désactivé. Ce sont eux qui font exploser le nombre de couleurs codées en dur.
• Ne pas documenter. Un token que personne ne trouve sera recréé sous un autre nom.

Par où commencer

1. Faites l’inventaire : couleurs, rayons, espacements, tailles de texte réellement utilisés dans le produit.
2. Décidez des valeurs à garder, et écrivez-les en tokens de référence.
3. Nommez les rôles dont vous avez besoin, et branchez-les sur ces références. Commencez petit : une quinzaine de rôles couvre la plupart des interfaces.
4. Faites lire ces rôles par vos composants, un par un, en commençant par le bouton.
5. Ajoutez le thème sombre en dernier : si les étapes précédentes sont faites, c’est l’affaire d’une heure.

Le design system de ce site suit exactement cette organisation. Appuyez sur S, ou ouvrez la page Design system, pour voir les tokens sur la page elle-même.