Le problème des valeurs en dur

Dans une base de code sans tokens, la même couleur d'accent apparaît des centaines de fois, écrite en hexadécimal. Le jour où la marque change de teinte, il faut toutes les retrouver, en oubliant forcément quelques-unes. Le jour où l'on veut un thème sombre, il faut décider écran par écran quelle valeur remplacer par quelle autre. Ce travail est long, risqué et entièrement évitable.

Les design tokens répondent à ce problème en donnant un nom aux décisions de design. Mais tous les tokens ne se valent pas, et la façon de les nommer fait toute la différence.

Trois couches, trois questions

Une architecture robuste sépare trois niveaux, chacun répondant à une question.

Les primitives : quelle valeur ?

C'est l'inventaire de tout ce qui est disponible : la rampe de gris, les teintes d'accent, l'échelle d'espacement. Les primitives sont nommées par leur apparence, par exemple --peach-400. Elles ne sont jamais utilisées directement dans un composant.

Les sémantiques : pour quoi faire ?

Ce sont des décisions. Quel gris pour le texte secondaire, quelle couleur pour une erreur, quelle surface pour une carte. Elles sont nommées par leur rôle, par exemple --fg-2 ou --danger, et pointent vers une primitive. C'est la couche que consomment les composants.

Les tokens de composant : où exactement ?

Quand un composant a besoin d'un réglage qui lui est propre, comme la hauteur d'un bouton ou le rayon d'une carte, on lui donne un token dédié qui pointe vers une sémantique ou une primitive. Cette couche reste petite : chaque token de composant est une exception justifiée.

Nommer le rôle, jamais l'apparence

La règle la plus importante tient en une phrase. Un token nommé --red devient faux le jour où les erreurs passent en orange. Un token nommé --danger reste juste. Un token nommé --gray-light ne dit pas s'il sert au texte ou aux bordures ; --line le dit.

Le nom d'un token est un contrat. La valeur peut changer, le rôle ne change pas.

Cette discipline a un coût au départ : il faut débattre des rôles, accepter de ne pas avoir un token par nuance, documenter chaque décision. Elle rapporte ensuite à chaque évolution.

Les thèmes deviennent presque gratuits

Avec une couche sémantique propre, un thème sombre redéfinit les sémantiques et laisse les composants intacts. --bg pointe vers le charbon le plus sombre au lieu du plus clair, --fg fait l'inverse, et tous les composants suivent. Le site que vous lisez fonctionne exactement ainsi : un seul jeu de composants, deux jeux de valeurs sémantiques.

Le même mécanisme permet de gérer plusieurs marques dans un groupe, une version dense pour les applications métier ou un thème à contraste renforcé. À chaque fois, on ajoute un jeu de valeurs et les composants restent les mêmes.

Les pièges fréquents

  • Trop de tokens : un token par usage précis rend le système illisible. Si deux rôles ont toujours la même valeur, fusionnez-les.
  • Des primitives dans les composants : un composant qui utilise --peach-400 ne suivra pas le changement de thème.
  • Des opacités à la place des tokens : un texte secondaire obtenu par transparence change de contraste selon le fond. Mieux vaut un token dédié dont on vérifie le contraste.
  • Des renommages sans alias : renommer un token casse tous les produits qui l'utilisent. L'ancien nom doit rester disponible pendant une version, avec un avertissement.

Pourquoi c'est encore plus important avec l'IA

Un modèle de langage qui génère une interface a besoin de savoir quelles valeurs utiliser. Si on lui donne une liste de couleurs hexadécimales, il choisira au hasard ou d'après leur apparence. Si on lui donne des tokens sémantiques avec une description de leur rôle, il peut raisonner : le texte d'aide prend --fg-3, le message d'erreur prend --danger. Le format JSON du Design Tokens Community Group du W3C (DTCG), avec ses champs de valeur, de type et de description, est particulièrement adapté à cet usage.

Dans mes projets de génération de code, cette couche a été décisive. Le code produit consommait des tokens au lieu de valeurs brutes, et une règle de lint rejetait le reste. Résultat : un code conforme dès la génération, sans refactoring.

Ce qu'il faut retenir

Les tokens sémantiques sont un investissement modeste qui structure tout le reste : thèmes, marques, maintenance, accessibilité et génération par IA. Ils obligent à expliciter des décisions qui restaient implicites. C'est exactement ce dont un système a besoin pour durer, et ce dont une machine a besoin pour le respecter.