Chapitre 4.1 — Tokens : la source de vérité

⏱️ TL;DR — La première cause d’incohérence visuelle : des valeurs de design en dur, éparpillées (un #3b82f6 ici, un p-4 là, un rounded-lg au hasard). Le remède est structurel : des tokens — des variables sémantiques (--color-brand, --radius-card, l’échelle d’espacement) définies à un seul endroit, dont chaque composant hérite. Quand la couleur de marque vit dans un token, l’agent ne peut plus en inventer une deuxième. La cohérence devient le chemin le plus facile.

🎯 Objectifs

Comprendre pourquoi les valeurs en dur produisent la dérive visuelle.
Définir des tokens sémantiques (pas seulement des valeurs brutes).
Rendre les tokens incontournables pour l’agent.
Distinguer token sémantique et token primitif.

Le problème des valeurs en dur

Quand l’agent écrit className="bg-[#3b82f6] p-4 rounded-lg", il fait un choix local et opaque. Le prochain écran écrira peut-être bg-blue-500 p-5 rounded-xl — proche, mais différent. Multiplié par 30 composants et 5 sessions, tu obtiens une UI « presque cohérente », c’est-à-dire incohérente. Le pire : rien n’est faux, donc rien ne saute aux yeux à la revue — la dette s’accumule en silence.

Sémantique, pas juste des variables

Une variable --blue-500: #3b82f6 est un progrès, mais ce n’est pas encore un vrai token de design. Le token sémantique dit le rôle, pas la valeur :


:root {
  /* primitifs (la palette brute) */
  --clay-500: #d97757;
  --slate-900: #0f172a;
 
  /* sémantiques (les rôles — c'est CE qu'on utilise dans les composants) */
  --color-brand: var(--clay-500);
  --color-surface: #ffffff;
  --color-text: var(--slate-900);
  --color-danger: #dc2626;
  --radius-card: 14px;
}

L’intérêt : un composant utilise --color-brand (le rôle), pas --clay-500 (la valeur). Le jour où la marque change, tu modifies une ligne (--color-brand: …) et tout suit. Et surtout, l’agent qui lit tes composants apprend à raisonner en rôles — « c’est une surface », « c’est du texte secondaire » — ce qui produit des choix cohérents même sur un écran nouveau.

💡 Réflexe d’architecte — Nomme tes tokens par intention, jamais par apparence. --color-danger, pas --color-red (et si demain le danger devient orange, le nom tient toujours). Un token bien nommé encode une décision de design que l’agent peut réutiliser ; un token « couleur » n’encode qu’une valeur.

Rendre les tokens incontournables

Définir des tokens ne suffit pas : il faut que l’agent ne puisse pas les contourner facilement. Trois leviers, dans l’esprit des couches (3.3) :

Énoncer (CLAUDE.md) : « Couleurs/espacements/rayons : tokens sémantiques uniquement. Jamais de hex ni de valeur arbitraire ([#…], p-[13px]) dans un composant. »
Montrer : le fichier-modèle (button.tsx) n’utilise que des tokens. L’exemple enseigne plus que la règle.
Imposer (quand possible) : configurer Tailwind pour exposer tes tokens comme classes (bg-brand, text-danger) et une règle de lint qui interdit les valeurs arbitraires (bg-[...]). L’agent n’a alors même plus la tentation.

⚠️ Piège — Créer des tokens puis laisser l’agent écrire des valeurs arbitraires « juste cette fois ». Chaque exception rouvre la porte. Si un besoin réel n’a pas de token (une nouvelle nuance), la bonne réponse est d’ajouter un token (une décision), pas d’écrire une valeur en dur (une dérive).

Les tokens minimaux d’un projet

Tu n’as pas besoin d’un système exhaustif. Un socle robuste :

Famille	Exemples de tokens	Note
Couleurs sémantiques	`brand`, `surface`, `surface-2`, `text`, `text-muted`, `border`, `danger`, `success`	le cœur
Espacement	échelle 4/8px (souvent l’échelle Tailwind suffit)	reste cohérent
Rayons	`radius-sm`, `radius-card`	2-3 valeurs
Ombres	`shadow-card`	1-2 valeurs
Typo	1 police, échelle de tailles, 2-3 graisses	sobriété

Sobre et sémantique bat riche et anarchique. On préfère 8 couleurs de rôle bien utilisées à 40 nuances au choix.

🧭 Sur TaskFlow — En 4.5, on posera les tokens sémantiques de TaskFlow (marque argile, surfaces, texte, danger/success), on les exposera en classes Tailwind, et on ajoutera la règle de lint anti-valeur-arbitraire. Dès lors, l’agent construira chaque écran avec la même palette, sans qu’on ait à le surveiller.

✏️ Exercices

Exercice 1 — Rôles, pas couleurs. Prends 6 couleurs de ton UI actuelle. Renomme-les par rôle (brand, surface, danger…). Y a-t-il deux couleurs qui jouent le même rôle (donc à fusionner) ?

✅ Solution

L’exercice révèle souvent des doublons : deux gris « texte secondaire » légèrement différents, deux bleus « lien ». Les fusionner en un seul token de rôle est la correction de cohérence. Nommer par rôle force à clarifier l’intention de chaque couleur.

Exercice 2 — Interdis l’arbitraire. Ajoute (ou demande à l’agent) une règle de lint interdisant les classes Tailwind à valeur arbitraire (bg-[...], p-[...]). Lance-la sur ton code : combien de violations ?

✅ Solution

Le nombre de violations mesure ta dette de tokens. Chaque [#…] ou [13px] est un endroit où le design a « fuité » hors du système. Les corriger (vers un token existant, ou en ajoutant un token si le besoin est réel) ramène l’UI dans le système — et empêche l’agent de récréer la dette.

🧠 Quiz de révision

1. Pourquoi les valeurs en dur produisent-elles une dérive « invisible » ?

Parce que chaque valeur locale est légèrement différente sans être fausse : rien ne saute aux yeux en revue, mais l’ensemble devient « presque cohérent » = incohérent. La dette s’accumule en silence.

2. Différence entre token primitif et token sémantique ?

Le primitif est la valeur brute (--clay-500: #d97757). Le sémantique est le rôle (--color-brand: var(--clay-500)), et c’est lui qu’on utilise dans les composants. Changer la marque = une ligne.

3. Pourquoi nommer par intention et non par apparence ?

Parce que --color-danger reste juste même si le danger passe du rouge à l’orange, tandis que --color-red ment. Le nom encode une décision de design réutilisable, pas une couleur.

4. Comment rendre les tokens incontournables ?

Les énoncer (CLAUDE.md), les montrer (fichier-modèle qui n’utilise que des tokens), et les imposer (classes Tailwind dédiées + lint interdisant les valeurs arbitraires).

5. Un écran a besoin d’une nuance sans token. Que fait-on ?

On ajoute un token (une décision de design centralisée), on n’écrit pas une valeur en dur (une dérive). L’exception « juste cette fois » rouvre la porte à l’incohérence.

Chapitre suivant : Primitives & réutilisation — empêcher l’agent de réinventer ce qui existe déjà.