Nommage des design tokens : le système à trois niveaux et ses limites

La convention est quasi universelle, ce qui rend facile l'adoption de la structure sans en comprendre la logique. Chaque niveau répond à une question différente, et savoir laquelle permet d'éviter de placer les éléments au mauvais endroit.

La règle qui permet au système de fonctionner, et celle qui est la plus souvent transgressée : rien en dehors du niveau sémantique ne peut référencer une primitive. Dès qu'un composant utilise blue-600 directement, le niveau primitive devient une API publique et vous ne pouvez plus modifier une valeur sans auditer l'ensemble de la base de code, ce qui était précisément la raison d'être des niveaux.

:root {
  /* Tier 1: primitives. Values only. Nobody uses these directly. */
  --blue-600: #2563eb;
  --red-600:  #dc2626;
  --gray-500: #6b7280;

  /* Tier 2: semantic. Roles. This is the public API. */
  --color-primary:   var(--blue-600);
  --color-danger:    var(--red-600);
  --text-muted:      var(--gray-500);

  /* Tier 3: component. Only where a component truly deviates. */
  --button-danger-bg: var(--color-danger);
}

/* ✅ product code */
.alert { color: var(--color-danger); }

/* ❌ reaches past the semantic layer */
.alert { color: var(--red-600); }

Lecture de gauche à droite, du général au spécifique : catégorie, rôle, variante, état. Tous les tokens n'ont pas besoin de ces quatre éléments, et ceux qui en ont sont généralement interactifs.

La cohérence importe bien plus que le modèle choisi. Une base de code où la moitié des tokens s'appellent text-color-muted et l'autre moitié color-text-muted oblige tout le monde à vérifier la syntaxe à chaque fois, indéfiniment. Choisissez un ordre, documentez-le et imposez-le lors des revues.

Voici le modèle appliqué plutôt que décrit. Lisez les noms de rôles, pas les couleurs. La question à laquelle chacun doit répondre est « à quoi cela sert-il ? » ; un nom qui répond seulement à « de quelle couleur est-ce ? » a échoué par rapport au niveau auquel il se situe.

Une seule question permet de trancher la plupart des débats de nommage en quelques secondes :

Appliquez ce test à des cas réels et les réponses sont sans ambiguïté :

Le cas de --shadow-card est subtil et mérite qu'on s'y attarde. Nommer un token d'après son implémentation fige cette implémentation. Une fois que chaque carte dans la base de code utilise box-shadow: var(--shadow-card), passer à une élévation basée sur des bordures devient un refactoring plutôt qu'un simple changement de token, ce qui est précisément le couplage que les tokens étaient censés supprimer.

La plupart des systèmes de tokens qui échouent le font ici. Le niveau des composants commence modestement et légitimement, puis absorbe tout, jusqu'à ce que vous vous retrouviez avec quatre cents tokens dont la moitié n'a qu'un seul utilisateur.

Le mécanisme est toujours le même. Quelqu'un a besoin d'un fond de bouton qui n'est pas tout à fait --color-primary. Ajouter --button-primary-bg prend trente secondes, alors que l'ajouter au niveau sémantique nécessite une discussion. Le token de composant est donc créé, la personne suivante fait de même, et le niveau sémantique cesse d'être la source de vérité sans que personne ne l'ait décidé.

Un audit utile : comptez les tokens de niveau composant qui n'ont qu'un seul utilisateur. Si ce nombre est élevé, le niveau est utilisé comme une solution de secours, et la correction doit se faire en amont.

Ces erreurs reviennent dans presque tous les systèmes de tokens qui finissent par être abandonnés. Chacune a une correction simple si elle est détectée tôt, et coûteuse dans le cas contraire.

1. 1

   Échelles numérotées sans point d'ancrage

   De color-1 à color-12 ne signifie rien pour personne, et les chiffres n'acquièrent un sens que par folklore. Les échelles numérotées sont acceptables dans le niveau primitif, où le chiffre suit une dimension réelle comme la luminosité. Elles ne sont jamais acceptables dans le niveau sémantique, car tout l'intérêt de ce niveau est d'indiquer à quoi sert l'élément.

2. 2

   Encoder le thème dans le nom

   Utiliser --light-bg et --dark-bg comme tokens distincts signifie que chaque composant doit référencer les deux et créer une condition. Un nom, deux valeurs, basculées par le thème : c'est à cela que sert la couche de tokens. Si vous trouvez if (theme === 'dark') dans le code d'un composant, c'est que les tokens sont mal nommés.

   Copy

   /* ❌ */  --light-bg: #fff;  --dark-bg: #0a0a0a;
   /* ✅ */  --surface-base: #fff;
            [data-theme="dark"] { --surface-base: #0a0a0a; }

3. 3

   Des tailles nommées selon leur usage actuel

   --text-hero convient parfaitement jusqu'à ce que la taille « hero » apparaisse dans un tableau de prix. --text-4xl ou --font-scale-7 nomment l'échelon, pas le site, et survivent à la réutilisation. Nommez par position dans une échelle, pas selon le premier client.

4. 4

   Des couleurs de statut servant également de couleurs de marque

   C'est la manière la plus courante pour un système de devenir incapable d'afficher un état. Si le vert de la marque et le vert de succès sont le même token, vous ne pouvez pas modifier le style de la marque sans changer l'apparence du succès, et vous ne pouvez pas distinguer une ligne saine d'une ligne brandée. Gardez l'ensemble des statuts réservé et précisez-le dans un commentaire.

5. 5

   Des abréviations que seule une personne sait interpréter

   --clr-bg-scndry économise onze caractères mais impose à chaque lecteur une étape de décodage permanente, y compris à un modèle qui doit deviner si scndry signifie « secondary » ou s'il s'agit d'une faute de frappe. L'autocomplétion rend la longueur quasi gratuite. Écrivez les mots en entier.

Les tokens doivent être de plus en plus portables : d'un outil de design vers le CSS, dans un thème Tailwind, dans une plateforme native, dans un élément de registre shadcn, ou dans un DESIGN.md lu par un agent. Cela impose une contrainte sur les noms que la plupart des équipes ignorent jusqu'à ce que le premier export échoue.

La règle pratique : choisissez des noms qui soient simultanément une propriété personnalisée CSS valide, une clé JSON valide et une phrase anglaise lisible. Le format plat, en minuscules et avec traits d'union satisfait ces trois conditions. De plus, les groupes imbriqués du format de token DTCG/W3C peuvent être générés à partir d'un ensemble plat bien plus facilement que l'inverse.

La décision de nommage ayant le plus d'impact n'est pas le pattern. C'est de savoir si les noms dans votre outil de design sont identiques aux noms dans le code.

Le SLDS 2 de Salesforce est l'exemple publié le plus clair : sa bibliothèque Figma utilise les mêmes noms de hooks sémantiques que le CSS (leurs propres exemples sont radius-border-4 et font-scale-4), ainsi les designs correspondent un pour un au code réel. Leur objectif affiché est un vocabulaire partagé faisant le pont entre le design et le développement.

L'effet concret est la disparition pure et simple d'une catégorie de bugs de handoff. Lorsqu'un designer dit font-scale-4 et qu'un développeur tape font-scale-4, il n'y a pas d'étape de traduction et donc aucun risque de perte de sens. Comparez cela à un style Figma appelé « Heading / Large » correspondant à une variable CSS appelée --text-2xl, où chaque handoff est une recherche et chaque recherche une occasion de se tromper.

Le nommage des tokens était autrefois une question d'ergonomie humaine : autocomplétion, lisibilité, onboarding. De plus en plus, le lecteur principal de votre fichier de tokens est un agent de code, ce qui change la nature des erreurs critiques.

Un humain qui ne sait pas lequel de deux gris utiliser posera la question, ou en choisira un et sera corrigé lors de la revue. Un modèle en choisira un, silencieusement, dans chaque fichier qu'il touchera, et l'incohérence s'installera plus vite que la revue ne pourra la détecter. L'ambiguïté dans le niveau sémantique est un défaut bien plus coûteux qu'auparavant.

Nous avons analysé 299 fichiers DESIGN.md publiés pour être lus par des agents et avons constaté que 86 % spécifient les couleurs par des valeurs hexadécimales brutes sans aucun rôle sémantique associé. Pas des tokens mal nommés : aucun token. Un modèle à qui l'on donne #6b7280 en lui disant qu'il fait partie de la palette l'utilisera partout où un gris moyen semble plausible : corps de texte, bordures, icônes, placeholders, états désactivés. Cinq fonctions différentes, une seule valeur, et aucun moyen de les modifier indépendamment plus tard.

La seconde version coûte trois lignes supplémentaires, mais elle permet d'assombrir vos bordures sans assombrir vos légendes, une modification indispensable que la première version rend impossible sans un audit complet de la base de code.

Si vous nommez un système de zéro, c'est le minimum défendable. Il est volontairement restreint. Un système que personne ne peut garder en tête finit par être ignoré.

/* Surfaces — what things sit on */
--surface-base        /* the page */
--surface-raised      /* cards, panels */
--surface-overlay     /* modals, popovers */
--surface-sunken      /* wells, inset areas */

/* Text — by emphasis, never by colour */
--text-primary
--text-secondary
--text-muted
--text-disabled
--text-on-accent      /* text sitting on the accent colour */

/* Borders — by weight of presence */
--border-subtle
--border-strong
--border-focus

/* Action — the interactive colour and its states */
--action-primary
--action-primary-hover
--action-primary-active

/* Status — reserved. Nothing decorative uses these. */
--status-success
--status-warning
--status-danger
--status-info

Deux notes sur cet ensemble. Les tokens de texte sont nommés par emphase plutôt que par couleur, afin de rester cohérents en mode sombre. Les tokens de statut comportent un commentaire de réservation, car la cause la plus fréquente de rupture d'un système de statut est un designer utilisant le vert de succès comme accent décoratif, rendant impossible la distinction entre une ligne saine et une ligne de marque.