Conventions de nommage des design tokens

Le nom d’un design token est un chemin, lu du plus large au plus étroit : category-concept-variant-state — comme dans color-background-subtle, space-4, text-heading-lg. Les conventions qui tiennent dans la durée suivent cinq règles : nommer la décision plutôt que la valeur, placer la position avant l’apparence pour les primitives, placer le rôle avant le contexte pour les sémantiques, réserver un ensemble fixe de suffixes d’état, et choisir une convention de casse une seule fois. Tout ce qui se trouve en dessous de ces règles — bg ou background, sm ou small — est une micro-décision à prendre une fois, à consigner, et à ne plus remettre en question.

Cet article couvre les conventions de nommage qui traversent toutes les catégories de tokens ; c’est le chapitre nommage de notre guide des design tokens. La couleur et la typographie ajoutent des arguments propres à leur domaine par-dessus ces règles — mais les règles elles-mêmes constituent le socle commun.

Comment un nom de token est-il structuré ?

Comme un chemin où chaque segment précise le précédent. La catégorie indique de quel type de valeur il s’agit (color, space, text) ; le concept indique quelle partie de l’interface elle sert (background, border, heading) ; la variante distingue les frères et sœurs (subtle, raised, lg, 4) ; l’état — lorsqu’il est présent — nomme une condition d’interaction (hover, disabled). Tous les noms n’utilisent pas les quatre segments : space-4 est une catégorie et une variante sans rien entre les deux, parce que l’espacement n’a aucun concept à distinguer.

Deux familles de conventions portent le même chemin. La casse à tirets l’écrit à plat — color-background-subtle — ce que veulent les propriétés personnalisées CSS. Les chemins à points l’écrivent sous forme d’imbrication — color.background.subtle — ce que produit le format DTCG, où les groupes sont des objets imbriqués et le nom est le chemin jusqu’à la feuille. La correspondance entre les deux tient en une ligne mécanique : remplacez les points par des tirets et préfixez par --, et tout chemin DTCG devient un nom de propriété personnalisée valide. Comme la correspondance est mécanique, le travail de conception — choisir les segments — se transpose sans changement d’un format à l’autre ; seule la ponctuation dépend du format.

Quelles règles de nommage survivent au contact du réel ?

1. Nommer la décision, pas la valeur. C’est la loi au cœur de ce que sont les design tokens, et chaque catégorie de token l’illustre : brand-600 survit à la refonte de marque qui fait virer la marque au bleu sarcelle, tandis que blue-600 soit ment sur son contenu, soit force un renommage dans tous les fichiers qui le référencent. La même loi exclut space-16px (faux le jour où le pas est réajusté à 14) et privilégie les noms qui énoncent à quoi sert un token — parce que ce « à quoi il sert » est le fait stable, et la valeur le fait volatil.

2. La position avant l’apparence, pour les primitives. 600 nomme une place dans une rampe ; dark décrit l’aspect qu’a la valeur aujourd’hui. Quand une rampe est réajustée — la courbe de luminosité modifiée, un pas inséré — les positions gardent leur sens tandis que les mots d’apparence cessent discrètement d’être vrais : blue-dark est-il toujours plus foncé que blue-darker après le réajustement ? Les positions numérotées survivent à chaque réajustement précisément parce qu’elles n’affirment jamais rien sur la valeur.

3. Le rôle avant le contexte, pour les sémantiques. text-primary nomme une fonction et se transpose à tout écran comportant du texte principal ; article-heading-color nomme un endroit et y reste bloqué. Les contextes se multiplient sans limite — article, carte, modale, barre latérale, réglages — tandis que les rôles restent dénombrables : la plupart des systèmes en ont besoin d’une douzaine ou deux. Nommer par rôle maintient l’ensemble de tokens à la taille de la liste des rôles plutôt qu’à la taille du produit.

4. Réserver les suffixes d’état. Déclarez un vocabulaire court et fixe — -hover, -pressed, -focus, -disabled, -selected — qui n’apparaît jamais qu’à la fin d’un nom et ne signifie jamais que l’état d’interaction. Le gain, c’est la prédiction : quiconque sait que fill-brand existe peut écrire fill-brand-hover sans ouvrir un fichier. Un vocabulaire non réservé se dégrade jusqu’à voir cohabiter fill-brand-hover, fill-brandHover2 et fill-brand-mouseover.

5. Choisir une convention de casse et ne jamais y revenir. kebab-case, camelCase ou chemins à points — les preuves de la supériorité de l’un sur l’autre sont minces, et c’est précisément pourquoi le débat ne se règle jamais sur le fond. Les conventions de nommage sont l’un des plus vieux aimants à débats de la programmation, et le nommage des tokens en hérite la taxe : une équipe peut y brûler des semaines, et ces semaines n’achètent rien, parce que n’importe quelle convention cohérente l’emporte sur une convention parfaite encore en discussion — c’est de la cohérence que dépendent les règles 1 à 4 et chaque export de la chaîne d’outils. Décidez en une réunion, consignez la décision, clôturez le sujet.

Ouvrez un système de tokens généré et lisez ses noms d’un format à l’autre — les mêmes chemins écrits sous forme de groupes DTCG, de propriétés personnalisées CSS et de noms de variables Figma, les segments visibles dans chaque rendu.

Faut-il écrire bg ou background, sm ou small ?

Le choix importe moins que le fait de choisir une fois et de le consigner. C’est dans ces micro-décisions que se cachent les débats de nommage une fois les grandes règles réglées ; voici donc un ensemble de choix défendables, avec une ligne de justification pour chacun :

Le rôle de ce tableau est d’être terminé, pas parfait. Si votre équipe en écrit déjà la moitié dans l’autre sens, gardez les choix existants et documentez-les — une convention cohérente héritée l’emporte sur une meilleure convention incohérente, ce qui n’est que la règle 5 sous d’autres habits.

Qu’est-ce qui fait un bon nom de token ?

Il peut être deviné par quelqu’un qui ne l’a jamais vu. Voilà le test pratique : montrez à un nouveau membre de l’équipe color-background-subtle et color-text-primary, puis demandez-lui comment s’appellerait une bordure discrète. S’il répond color-border-subtle — et que ce token existe — la convention fait son travail.

La raison intuitive pour laquelle la prévisibilité compte plus que l’élégance : une convention de nommage est une petite grammaire, et les gens généralisent automatiquement à partir des grammaires après une poignée d’exemples. Les noms qui suivent la grammaire sont devinés plutôt que cherchés — chaque bonne prédiction est une recherche dans la documentation qui n’a jamais lieu, un quasi-doublon qui n’est jamais créé, un commentaire de revue qu’on n’a jamais à écrire. Les noms qui enfreignent la grammaire coûtent chacun une consultation, pour toujours. Le test fonctionne aussi à l’envers : si chaque nom exige d’ouvrir la documentation, c’est que les noms ne portent aucune structure digne d’être apprise.

À quoi ressemble l’ensemble de tokens d’un composant, bien et mal nommé ?

Un composant carte requiert cinq décisions de couleur. Les voici deux fois — d’abord telles que les ensembles de tokens s’accumulent quand personne ne tient une convention, puis en suivant les règles ci-dessus :

Les deux colonnes rendent la même carte aujourd’hui. Les problèmes de la colonne de gauche sont tous des problèmes futurs : trois conventions de casse en cinq noms (règle 5) ; blueDark nomme une valeur et mentira après une refonte de marque (règle 1) ; card_outline_gray enfreint deux règles en un seul nom — un contexte et une apparence — si bien que le prochain composant qui a besoin de la même bordure soit emprunte un token « carte », soit crée un doublon (règles 2 et 3) ; cardBgHover2 porte un état non réservé et un mystérieux numéro de série (règle 4). La colonne de droite se résout à travers une couche sémantique en pas de rampe dérivés d’une seule couleur de départ — sur cette palette #2563eb, soit oklch(0.546 0.215 262.9) — et son sixième token est devinable avant même d’exister : un état pressé sur le bouton serait color-fill-brand-pressed, et chaque lecteur le sait déjà.

Éprouvez les noms face au changement

Un schéma de nommage fait ses preuves lors d’événements, pas en réunion de revue : refontes de marque, réajustements de rampe, mode sombre. Chargez un fichier de tokens et renommez une primitive nommée par sa valeur en un nom de décision — réexportez, et l’aller-retour préserve chaque section que vous n’avez pas touchée ; puis changez la couleur de départ et regardez le token renommé continuer à dire vrai tandis que la valeur en dessous se déplace.