Primitive, sémantique, composant : les trois couches de tokens

« Le changement de marque était budgété à trois jours. Il en a pris trois semaines. » Le post-mortem derrière cette phrase est généralement le même : l’ancienne couleur de marque existait sous forme de hex brut, collé dans des centaines de composants, si bien que « remplacer le bleu par le turquoise » n’était pas un seul changement — c’était un rechercher-remplacer à travers toute la base de code, plus une revue de chaque endroit où le remplacement s’était trompé. Rien n’était mal construit ; il n’existait tout simplement aucune couche où « la couleur de marque » existait en tant que décision unique.

L’architecture de tokens empêche exactement cela, avec jusqu’à trois couches. Les tokens primitifs sont le vocabulaire brut — brand-600, space-4, text-lg — des valeurs aux noms positionnels, sans opinion sur leur usage. Les design tokens sémantiques sont les décisions — background, text-primary, accent, gap-section — des noms de rôle qui pointent vers des primitives ; c’est là que vit l’intention de design. Les tokens de composant — button-bg pointant vers accent — forment une troisième couche facultative, pour les cas où un composant doit se détacher d’une valeur sémantique par défaut. Les composants lisent la couche sémantique, et les changements courants — changement de marque, thème, exception — se posent chacun dans une seule couche. Le concept général de token a son propre article dans notre guide des design tokens ; celui-ci porte sur le modèle de couches lui-même.

Que fait chaque couche ?

Les primitives sont la palette et les échelles : brand-50 jusqu’à brand-900, space-1 jusqu’à space-7, text-sm jusqu’à text-xl. Leurs noms énoncent une position, jamais une fonction — brand-600 vous indique quel bleu, et délibérément rien sur l’endroit où il appartient. Elles sont le vocabulaire du système : tout ce qui peut être dit, rien encore de dit.

Les tokens sémantiques disent des choses. background → neutral-50, text-primary → neutral-800, accent → brand-600, gap-section → space-7 : chacun est une décision de design — ce rôle est joué par cette valeur — consignée sous forme de référence. Quand quelqu’un demande où l’intention de design d’un produit est écrite noir sur blanc, cette couche est la réponse.

Les tokens de composant consignent les exceptions. button-bg n’a normalement aucune raison d’exister — le bouton peut lire accent directement. Il gagne sa place le jour où le bouton doit cesser de suivre accent : un thème marketing repointe accent vers une teinte secondaire, mais le bouton principal doit rester fidèle à la marque. Le token de composant consigne ce détachement.

Le système de tokens de Material Design documente la même architecture à trois niveaux — tokens de référence, de système et de composant — dans son aperçu des design tokens, sous d’autres noms de couche.

Quelles règles font fonctionner les couches ?

Trois règles, chacune protégeant une propriété différente :

• Les composants consomment du sémantique, jamais des primitives. Un composant qui lit brand-600 a codé en dur une hypothèse sur quel échelon fait quel travail aujourd’hui ; un composant qui lit accent énonce un besoin et laisse le système y répondre. C’est cette règle qui rend les changements de marque et les thèmes peu coûteux — enfreignez-la et la couche au-dessus de la brèche cesse de vous protéger.
• Le sémantique pointe vers le bas, d’un seul saut. Un token sémantique référence une primitive, pas un autre token sémantique. Des chaînes comme button-text → text-inverse → on-dark → neutral-50 passent pour de la flexibilité mais coûtent en navigabilité : personne ne peut résoudre une valeur sans partir en exploration. Un seul saut permet de répondre à chaque rôle en une seule consultation.
• Les primitives ne référencent rien. Elles sont le socle. Chaque tracé, suivi vers le bas, se termine sur une primitive détenant une valeur littérale — c’est ce qui rend les tracés finis et les fichiers débogables.

Pourquoi les couches valent-elles mieux qu’une liste plate de tokens ?

Parce que chaque changement a un coût. Dans un système en couches, les trois changements courants ne touchent chacun qu’une seule couche :

Dans une liste plate — ou pire, des valeurs brutes dans les composants — chacun d’eux devient le changement de marque de trois semaines de l’introduction : un rechercher-remplacer à travers tout, avec un jugement à porter à chaque occurrence, car le même #2563eb qui signifiait « marque » dans un fichier signifiait « couleur de lien qui se trouve correspondre » dans un autre.

Le « pourquoi » intuitif mérite d’être énoncé pour ce qu’il est, un parallèle avec la programmation : les couches sont de l’indirection, et l’indirection est la façon dont le logiciel a toujours contenu le changement — la même raison qui fait que le code appelle des fonctions au lieu d’en répéter le corps. Un token sémantique est une interface ; les primitives sont l’implémentation ; et les changements cessent de se propager à la frontière entre les deux. Les design systems n’ont pas inventé l’astuce, ils en ont hérité.

À quoi ressemble un tracé complet ?

Vers le bas, depuis un composant : button.background lit {semantic.accent} ; accent lit {color.brand.600} ; brand-600 stocke #2563eb, soit oklch(0.546 0.215 262.9). Trois sauts, chacun une décision distincte. La même forme vaut hors de la couleur : gap-section lit {spacing.7}, qui stocke 64px.

Vers le haut, depuis une valeur : #2563eb est stocké exactement une fois, à brand-600. Un seul rôle sémantique pointe vers lui — accent. Demandez ce qui consomme accent et vous obtenez le rayon d’impact complet d’un changement de couleur de marque : le bouton, les liens, l’état de navigation actif — un ensemble fini et énumérable, au lieu de « partout où le hex a été collé ».

Ouvrez la vue de tracé dans Scale Composer — les rampes et échelles primitives d’un côté, les rôles sémantiques qui pointent vers elles, et la chaîne de n’importe quel rôle lisible saut par saut jusqu’à la valeur stockée.

Voici maintenant le test du changement de marque, la preuve du système en couches : re-dérivez la palette à partir d’une couleur de départ turquoise. brand-600 garde son nom et change sa valeur stockée. accent dit toujours {color.brand.600} — en tant qu’énoncé, il est intact et toujours vrai. button.background dit toujours {semantic.accent}. Le changement s’est produit dans une seule couche, et les couches au-dessus n’ont pas bougé. Voilà le changement de marque de trois semaines réduit à sa taille honnête : une modification et une revue.

Quand est-il honnête de sauter une couche ?

La couche de composant, souvent. Un petit produit doté d’une couche sémantique disciplinée a rarement des cas de détachement, et des tokens de composant créés avant le besoin sont de l’indirection sans signification — button-bg → accent → brand-600, trois noms pour une valeur qui ne varie jamais indépendamment, multipliés à travers une bibliothèque de composants jusqu’à ce que personne ne puisse naviguer dans l’ensemble. La couche gagne sa place à l’échelle d’un design system, quand de vraies exceptions apparaissent — une règle raisonnable par défaut est d’introduire chaque token de composant avec l’exception qui le justifie, pas avant.

La couche sémantique est celle à conserver même quand le système est petit. N’avoir que des primitives signifie que les composants fossilisent des hypothèses (brand-600 signifiant « couleur de bouton » à cent endroits), ce qui n’est autre que l’histoire d’ouverture sous de meilleurs noms. Primitives plus sémantique, c’est le minimum honnête pour un système qui s’attend à survivre à un changement de marque ou à voir grandir un thème sombre.

Faites le test du changement de marque vous-même

On fait le plus facilement confiance au modèle de couches après avoir vu un changement s’arrêter à une frontière. Changez la couleur de départ et regardez les couches à l’œuvre — la rampe primitive se re-dérive, les rôles sémantiques se repointent automatiquement et gardent leurs noms, et le tracé depuis le bouton vers le bas se résout toujours — mêmes énoncés, nouvelles réponses, aucun rechercher-remplacer.