design.md vs Tokens de Design pour les Workflows d'UI IA

Je m’appelle Dora. Je passe la majeure partie de ma semaine dans des agents de codage et des outils d’interface IA — Cursor, Claude Code, Stitch, la liste habituelle — à construire et reconstruire des interfaces plus vite que je n’ai le temps de les documenter. Il y a environ un mois, j’ai commencé à voir le même fichier apparaître dans chaque autre dépôt que je touchais : DESIGN.md. Même nom, même structure YAML-en-haut-prose-en-bas. Au troisième projet, j’ai compris que ce n’était pas une coïncidence. C’était la chose qui remplaçait ce que la plupart d’entre nous avaient l’habitude de livrer sous forme de tokens.json.

Alors j’ai reconstruit l’une de mes propres bibliothèques de composants deux fois — une fois avec un fichier de tokens au style DTCG classique, une fois avec un DESIGN.md — et j’ai fait tourner le même agent de codage sur les deux. Voici la partie de la comparaison que je n’ai pas trouvée écrite nulle part : pas ce qu’est chaque format, mais pour quoi chacun est réellement optimisé, et lequel appartient à votre stack en ce moment.

design.md vs les design tokens traditionnels

Pour quoi chaque format est optimisé

Les design tokens, au sens classique, sont une méthodologie. Le terme a été inventé chez Salesforce vers 2014 pour résoudre un problème de mise à l’échelle très spécifique : comment garder une décision de couleur synchronisée entre le web, iOS, Android et quatre bases de code sans ouvrir quatre tickets ? La réponse était une paire nom-valeur agnostique à la plateforme, stockée en JSON ou YAML, transformée au moment du build en ce que chaque plateforme nécessitait. Cette méthodologie est désormais codifiée par le Design Tokens Community Group au W3C, et fin 2025, le format DTCG dispose d’une spécification v1 stable.

Les tokens optimisent pour la distribution déterministe. Un code hexadécimal entre, le même code hexadécimal sort sur chaque plateforme, à chaque build, pour toujours. Il n’y a pas d’ambiguïté. Il n’y a pas non plus de récit — un fichier de tokens vous dit primary: #1A1C1E mais ne vous dit pas pourquoi cette couleur existe ou quand ne pas l’utiliser.

DESIGN.md, rendu open-source par Google Labs en avril 2026, optimise pour quelque chose de différent : donner à un agent de codage suffisamment de contexte pour prendre des décisions que le fichier de tokens ne couvre pas. C’est un seul fichier markdown avec un en-tête YAML pour les tokens et de la prose en dessous pour la justification. Même fichier, deux audiences — la partie déterministe pour les parseurs, la partie narrative pour n’importe quel LLM qui lit le dépôt.

C’est la vraie distinction. Pas « ancien vs nouveau ». Pas « JSON vs Markdown ». C’est les valeurs vs les valeurs plus le raisonnement dans le même fichier.

Pourquoi les agents IA créent un nouvel ensemble d’exigences

Quand un humain implémente un design, l’écart entre « le token dit #1A1C1E » et « cet état vide a besoin d’un certain ton » est comblé par l’humain. Il a vu le fichier Figma. Il a participé à l’atelier de marque. Il sait que le bouton secondaire est censé sembler discret, pas assertif.

Un agent de codage n’a rien de tout cela. Il a ce que vous avez mis dans le dépôt et ce qu’il peut inférer des noms de fichiers. Donc quand vous lui demandez de générer un écran que le fichier de tokens ne spécifie pas complètement — un cas limite, un nouveau composant, une décision de mise en page — il devine ou revient à ce qu’il a vu le plus souvent lors de l’entraînement. C’est la source de l’esthétique « IA beige » dont tout le monde se plaint : pas de mauvais modèles, juste du contexte manquant.

C’est ce que DESIGN.md résout. La spécification officielle sur GitHub est explicite à ce sujet — les tokens donnent aux agents des valeurs exactes, la prose leur dit pourquoi ces valeurs existent et comment les appliquer. Le format attend les deux moitiés.

Où design.md apporte de la valeur

Contexte narratif persistant

Ce que j’ai remarqué dans les premières 48 heures de test : le même agent, avec le même brief, génère un résultat nettement différent lorsqu’un contexte en prose est présent. Pas « des couleurs légèrement meilleures ». Des choix de mise en page différents, un registre de texte différent, une densité de composants différente. Les valeurs des tokens étaient identiques dans les deux runs — ce qui avait changé, c’était si l’agent avait un paragraphe disant « la voix de la marque est retenue et éditoriale ; favoriser l’espace blanc plutôt que la décoration ».

C’est la partie que le pipeline de tokens traditionnel ne transporte pas. Un fichier JSON DTCG peut décrire --color-primary avec précision, mais il ne peut pas dire à un agent que la couleur primaire est censée être utilisée avec parcimonie. DESIGN.md transporte ce jugement dans chaque passe de génération, de manière persistante, sans que personne ne le retape dans une invite.

Ça marche.

Meilleure cohérence multi-écrans pour les workflows de génération

Dans mon deuxième test, j’ai généré huit écrans pour la même application sur deux jours. Avec uniquement le contexte des tokens, les écrans 5–8 ont commencé à dériver — même palette, mais le langage de mise en page s’est détendu. Avec DESIGN.md présent, la dérive était beaucoup plus petite. Pas nulle. Plus petite.

Mon interprétation : la section prose agit comme un re-ancrage chaque fois que l’agent lit le fichier. Les tokens seuls donnent à un agent assez pour être correct sur les valeurs individuelles. Le récit lui donne assez pour être cohérent à travers des décisions que les tokens n’anticipaient pas. Pour une génération ponctuelle, cet écart n’a pas d’importance. Pour des sorties multi-écrans et une itération continue, il s’accumule.

C’est aussi là que DESIGN.md s’intègre bien dans la pile d’instructions d’agent plus large — la plupart des configurations y font désormais référence depuis un AGENTS.md aux côtés des fichiers SKILL.md, de sorte que le système de design se trouve dans la même couche de contexte que le reste des instructions persistantes de l’agent.

Où les tokens traditionnels l’emportent encore

Deux scénarios, tous deux réels.

Distribution multiplateforme au-delà du web. Si vous livrez le même système de design sur iOS, Android, une application React Native et un site marketing, le pipeline DTCG via Style Dictionary ou Terrazzo est toujours le chemin de moindre résistance. Le YAML de DESIGN.md peut exporter vers DTCG JSON via la CLI officielle @google/design.md, mais la question de la source de vérité compte toujours — si votre graphe de tokens est grand, multi-thème et consommé par des outils non-IA, garder DTCG comme format canonique est la configuration la plus propre.

Systèmes de design matures avec une gouvernance établie. Les tokens ne sont pas seulement un format de fichier. Ce sont une méthodologie avec environ une décennie de pratique accumulée — couches primitives, couches sémantiques, aliasing, thèmes, toute la taxonomie que Nathan Curtis a exposée dans Tokens in Design Systems. Si votre équipe fonctionne déjà ainsi, DESIGN.md ne le remplace pas. Il se pose dessus, ou à côté, comme une couche de contexte pour les agents. Les tokens restent la source canonique ; le markdown devient la traduction orientée IA.

L’erreur serait de lire DESIGN.md comme un remplacement du pipeline de tokens. Ce n’est pas le cas. C’est une couche différente avec un consommateur différent.

Un cadre de décision pour les équipes construisant des pipelines d’interface IA

Je reviens sans cesse à quatre questions pour décider quoi mettre dans un dépôt :

1. Qui lit ce fichier ? Si le consommateur principal est un pipeline de build qui émet du CSS, Swift et Kotlin, vous voulez des tokens dans un format canonique. Si le consommateur principal est un agent de codage qui génère de l’interface à la demande, vous voulez DESIGN.md. Si c’est les deux, vous gardez les deux — et laissez le YAML du fichier markdown refléter un sous-ensemble des tokens.
2. À quelle fréquence votre surface d’interface est-elle régénérée ? Les équipes à faible fréquence (un produit stable, des nouveaux écrans occasionnels) tirent la majeure partie de leur valeur des tokens. Les équipes à haute fréquence (prototypage rapide, itération pilotée par agent, de nouveaux écrans chaque semaine) ressentent acutement l’écart de contexte manquant. Plus la fréquence de régénération est élevée, plus la couche de prose mérite sa place.
3. Combien de plateformes ? Web uniquement ou web-principalement avec génération pilotée par agent — DESIGN.md est la stack la plus simple. Trois plateformes ou plus avec une présence native sérieuse — tokens en premier, avec DESIGN.md comme artefact en aval.
4. La justification est-elle déjà documentée quelque part ? Si vos directives de marque, votre document de voix et votre philosophie de composants vivent dans une page Notion qu’aucun agent ne lira jamais, DESIGN.md est le geste à plus fort levier que vous pouvez faire ce trimestre. Vous ne créez pas de nouvelle documentation — vous déplacez la documentation existante dans un fichier que l’agent ouvre réellement.

C’est mon cadre. Le vôtre pourrait différer. Ce que je signalerais : ne choisissez pas un format parce qu’il est nouveau. Choisissez-le en fonction de qui lit le fichier.

FAQ

design.md remplace-t-il les design tokens ?

Non. DESIGN.md est une enveloppe qui contient des design tokens (dans l’en-tête YAML) ainsi que la justification autour d’eux (dans la prose markdown). Les tokens à l’intérieur sont toujours des design tokens au sens conventionnel. Si vous avez déjà un fichier de tokens au format DTCG, DESIGN.md ne le remplace pas — il se place comme artefact parallèle pour les agents IA, ou vous pouvez faire exporter du DTCG JSON par le markdown si nécessaire.

Pourquoi les agents IA auraient-ils besoin de plus que des tokens numériques ?

Parce que la plupart des demandes de génération d’interface ne sont pas entièrement spécifiées par le graphe de tokens. « Générer une page de tarification » nécessite des centaines de micro-décisions — hiérarchie, densité, ton, ce qu’il faut mettre en évidence — qu’aucun fichier de tokens ne couvre. Sans contexte narratif, l’agent comble ces lacunes avec ce qu’il a vu dans les données d’entraînement, ce qui produit l’apparence générique que partagent la plupart des interfaces générées par IA. La prose dans DESIGN.md est ce qui comble cet écart.

Quels workflows bénéficient le plus de design.md ?

Trois modèles que j’ai vus les plus payants :

• Les builders solo et les petites équipes utilisant Cursor, Claude Code ou Stitch pour livrer de l’interface plus vite qu’ils ne peuvent l’écrire à la main.
• Les équipes de systèmes de design gérant plusieurs produits internes où la cohérence entre les écrans générés par IA devient un vrai problème.
• Les agences et les équipes contractuelles qui veulent un seul fichier clé en main qui encode le langage de design d’un client pour n’importe quel agent de codage.

Si votre workflow est principalement codé à la main avec une assistance IA occasionnelle, la valeur marginale diminue.

Quand l’infrastructure classique de design tokens est-elle encore suffisante ?

Quand vous ne générez pas d’interface avec des agents, ou quand votre portée de plateforme s’étend bien au-delà du web. Mobile natif lourd, produits white-label multi-thèmes, pratiques de design ops matures — ceux-ci tirent encore plus du système DTCG que d’un fichier markdown. Les deux ne sont pas mutuellement exclusifs, mais si vous devez en choisir un dans lequel investir, la réponse dépend de l’endroit où se situe réellement votre friction de génération.

Conclusion

La version honnête : DESIGN.md n’est pas un changement de paradigme. C’est une solution ciblée à un écart spécifique — les agents de codage manquant de la justification que les fichiers de tokens ne transportent pas. Pour les workflows où cet écart est réel, le gain est immédiat et évident. Pour les workflows où il ne l’est pas, les tokens traditionnels font encore le travail.

Je suis deux mois dans l’utilisation de DESIGN.md sur chaque projet de génération IA que je gère. Il est resté dans le workflow, ce qui est le seul test auquel je fais confiance. Les fichiers de tokens ne sont nulle part non plus — ils font toujours ce qu’ils ont toujours fait, juste avec un fichier frère maintenant pour l’audience qui a besoin de plus que des chiffres.

Essayez-le vous-même sur un projet. Deux jours vous en apprendront plus que cet article ne peut le faire.

Articles précédents :

• GitHub Copilot vs Private Coding Assistants
• Claude Code vs Cursor 2026
• MCP in Production: Model Context Protocol Workflows
• Agentic Workflow Tool Wiring Patterns & Pitfalls
• Claude Code Agent Harness Architecture