Design tokens vs guide de style

Le nouveau portail de marque a été lancé sous les applaudissements : chaque couleur peinte en un généreux échantillon, les codes hex composés dans les légendes, des diagrammes d’espacement, une page par composant. En moins d’un an, il était silencieusement faux. Une correction de contraste avait légèrement décalé le bleu de marque dans le code ; le portail affichait toujours l’ancienne valeur ; et les designers avaient appris à prélever la couleur à la pipette depuis l’écran de production le plus récent. La documentation la plus soigneusement réalisée de l’entreprise était devenue la moins fiable.

Un guide de style et les design tokens documentent deux moitiés différentes d’un même système : le guide de style porte l’intention et l’usage pour les humains — quand chaque niveau de titre s’applique, comment la voix sonne, à quoi ressemble un contre-exemple — tandis que les tokens portent les valeurs pour les machines, sous forme d’entrées nommées qu’une étape de build lit directement. Ils se composent par référence : le guide moderne nomme les tokens (accent, space-4) au lieu d’intégrer leurs valeurs, il ne peut donc pas se périmer comme l’a fait ce portail. Cet article adopte le point de vue de l’architecture de documentation ; les fondamentaux des tokens se trouvent dans notre guide des design tokens. (Si les termes se brouillent : un système de design est le parapluie, et le guide de style et le fichier de tokens en sont deux des strates — cet article porte sur la façon dont ces deux-là se partagent le travail.)

Que fait un guide de style que les tokens ne peuvent pas faire ?

Un guide de style est un ensemble de standards sur la manière dont les choses sont conçues et rédigées, et son contenu irremplaçable est le jugement, pas les chiffres. Quand utiliser quel niveau de titre, et pourquoi en sauter un fait mal. Ce que la photographie devrait évoquer, montré côte à côte par un bon et un mauvais exemple. Pourquoi la couleur d’accent est réservée aux actions, et la justification d’accessibilité derrière les associations autorisées. Comment la marque sonne — avec la phrase qu’elle dirait et celle qu’elle ne dirait pas.

Rien de tout cela n’entre dans un schéma de tokens. Un token peut affirmer que text-primary est un quasi-noir particulier ; il ne peut pas expliquer ce qui compte comme texte principal, ni contenir un contre-exemple — qui est l’une des formes les plus denses en information de la documentation de design et n’a aucun équivalent en token. C’est le vrai travail du guide de style, et la tokenisation n’y touche pas. Ce qui meurt, ce n’est que l’autre habitude du guide : porter des valeurs.

Que contiennent les design tokens qu’un guide de style ne peut pas contenir ?

Les réponses exactes. brand-600 est un bleu précis — #2563eb, soit oklch(0.546 0.215 262.9) — stocké une seule fois, dans un fichier que Figma, un build de feuille de style et une application native lisent sans humain entre les deux. Un guide ne peut qu’afficher une image de cette valeur et espérer que chaque lecteur l’extraie fidèlement ; le token est la valeur, sans étape de rendu à survivre ni lecteur pour l’approximer.

Comment les guides de style sont-ils devenus « vivants », et pourquoi n’était-ce pas suffisant ?

L’histoire se déroule en trois générations. La première était statique : manuels imprimés, puis PDF et pages web, avec les valeurs peintes dans des échantillons et des légendes — des copies datant du jour de leur publication. La deuxième, le guide de style vivant, générait ses pages à partir du code de production, si bien que les échantillons montraient ce qui était réellement en production — mais il restait en lecture seule : un miroir des valeurs plutôt qu’une source de celles-ci, vrai tant que vous le regardiez, sans autorité sur le changement suivant. La troisième forme inverse la relation : la documentation référence les tokens par leur nom, le fichier de tokens possède les valeurs, et les autres artefacts — y compris les échantillons du guide lui-même — en sont rendus. Un guide construit ainsi ne peut pas mentir sur les valeurs, parce qu’il n’en porte aucune.

Pourquoi les valeurs documentées pourrissent-elles ?

Parce que chaque valeur qu’un document intègre est une copie, et les copies entretenues par des mains différentes finissent par diverger — le même mécanisme en une phrase derrière la plupart des histoires de dérive entre design et code. Un guide qui indique #2563EB est correct jusqu’au premier réajustement n’importe où ailleurs dans le système ; un guide qui indique brand-600 reste correct à travers chaque réajustement, parce qu’il énonce une relation plutôt qu’un instantané. La version intuitive : une copie peut se périmer, un pointeur non. Demander au lecteur de rechercher une chose est le prix à payer pour ne jamais rien lui dire de faux.

À quoi ressemble la même documentation de bouton dans les deux approches ?

Avec valeurs intégrées, comme l’écrivait le portail de première génération :

Les boutons principaux utilisent le bleu de marque (#2563EB) comme fond, avec un texte blanc, 16px de padding latéral et un rayon de coin de 6px.

Avec référence aux tokens :

Les boutons principaux utilisent accent comme fond, avec un texte on-accent, un padding latéral space-3 et des coins radius-sm. N’en utilisez qu’un par vue, pour l’action principale de la page ; tout le reste prend un bouton secondaire. Les valeurs actuelles vivent dans le fichier de tokens.

Faites maintenant passer un changement de marque par les deux. La palette se redérive à partir d’une couleur de départ turquoise : brand-600 garde son nom et stocke une nouvelle valeur, et accent — le rôle que nomme la documentation du bouton — pointe toujours vers lui. Le paragraphe qui référence les tokens est intact et toujours vrai. Le paragraphe à valeurs intégrées énonce désormais un hex faux — et ses trois autres valeurs intégrées (blanc, 16px, 6px) sont des risques distincts, chacun en attente de son propre réajustement. Remarquez aussi ce pour quoi la version en tokens a gagné de la place : libérée de porter des valeurs, elle consacre sa longueur à l’usage — un par vue — qui est le contenu qu’un guide existe pour contenir.

Ouvrez dans Scale Composer les rôles que nomme cette documentation — la couche sémantique avec accent, on-accent et le reste des rôles dérivés, à côté de leurs valeurs actuelles et des planchers de contraste face auxquels chaque association est vérifiée. C’est la moitié de la paire vers laquelle pointe un guide référençant des tokens : réajustez la couleur de départ et les noms tiennent tandis que les valeurs répondent différemment.

Comment les tokens, la documentation et les exemples se composent-ils ?

En trio, avec une seule direction de référence. Le fichier de tokens détient les valeurs. Le guide de style détient l’intention et l’usage, nommant les tokens partout où une valeur est visée. Les exemples vivants — composants rendus, pages d’échantillons, textes spécimens — sont générés à partir du fichier de tokens, si bien que même les images sont des vues de la source plutôt que ses rivales. Chaque artefact fait le seul travail auquel il est structurellement adapté : la prose transfère le jugement, les tokens transfèrent les valeurs, et les exemples rendus transfèrent la gestalt que ni la prose ni le JSON ne peuvent transmettre. Les équipes font parfois tourner le trio en paire — les tokens plus un guide qui les référence, les exemples reportés — et ça marche ; se réduire à un seul artefact est l’arrangement qui échoue, quel que soit celui qu’on garde.

Réécrivez un paragraphe de votre guide

Le changement est plus facile à juger sur un seul paragraphe. Prenez une règle porteuse de valeurs de votre guide actuel — la spécification de bouton ci-dessus sert de modèle — et réécrivez-la pour nommer des rôles au lieu d’intégrer des chiffres. Générez le jeu de tokens que votre guide pourra référencer — amorcez-le avec votre couleur de marque, laissez les rôles dérivés devenir les noms vers lesquels pointe votre documentation, et exportez le fichier pour que les valeurs du guide aient un foyer qui n’est pas le guide.