Design Tokens, DESIGN.md et Design to Code

Les agents de codage IA écrivent du code qui fonctionne, mais l'UI qu'ils produisent a l'air générique. Chaque app générée a l'air d'avoir été construite avec les mêmes composants par défaut, parce que c'est le cas. L'agent n'a pas d'ancrage pour ta marque. Dis-lui de « créer un bouton secondaire » et il invente une couleur. Dis-lui de « mettre l'app en dark mode » et il inspecte chaque composant, devinant quelles couleurs remplacer.

L'autre moitié du problème, c'est la fidélité. Tu conçois quelque chose dans un outil de design, tu le transmets, et le code qui revient ne correspond pas. L'espacement est faux, les couleurs sont proches mais pas justes, l'échelle typographique a disparu. Le design avait une structure, mais le handoff l'a perdue.

Ce sont les problèmes que tout un ensemble d'outils et de formats essaie de résoudre en ce moment. Le fil commun, ce sont les design tokens, et le format qui les porte vers les agents IA s'appelle DESIGN.md. Ce post est ce que j'ai appris en essayant de comprendre comment les pièces s'emboîtent.

Les tokens portent du sens, pas seulement des valeurs

Un design token est une valeur nommée. Au lieu de stocker #2563EB sur un bouton, tu stockes color.primary. Au lieu de 8px sur un coin, tu stockes radius.md.

La différence, c'est l'intention. Quand quelqu'un, ou quelque chose, regarde une valeur brute, tout ce qu'il voit, c'est la valeur. Un rectangle bleu avec des coins de 8px. Il doit deviner : est-ce le bouton primaire ? Ce bleu est-il utilisé ailleurs ? 8px est-il une décision délibérée ou un nombre que quelqu'un a tapé ?

Avec un token, l'intention est lisible. color.primary dit à quoi sert la couleur. radius.md dit que c'est partie d'une échelle, pas un nombre arbitraire. Un développeur qui lit ça n'a pas à deviner. Un agent IA qui lit ça n'a pas à deviner.

Le même token, color.primary, devient --color-primary en CSS, Color.primary sur iOS, theme.colors.primary dans Tailwind. Une décision, exprimée dans le langage de chaque plateforme. C'est ce que les gens veulent dire quand ils appellent les design tokens une source unique de vérité.

Un design system, c'est toute la structure. Les tokens sont les variables à l'intérieur. La relation ressemble à ça :

Design System
│
├── Foundations
│   │
│   ├── Tokens
│   │   ├── Colors
│   │   ├── Typography
│   │   └── Spacing
│   │
│   └── Themes
│       ├── Light
│       └── Dark
│
├── Components
│   ├── Button
│   ├── Card
│   └── Input
│
└── Documentation
    ├── Usage rules
    └── Examples

Ça vaut la peine de noter que Light et Dark ne sont pas le design system lui-même. Ce sont des thèmes à l'intérieur. Les tokens sont les variables qui permettent aux thèmes de basculer. Les composants consomment les tokens. Le design system, c'est le tout.

Un token ne sert pas à dessiner

C'est là que je l'avais à l'envers. Je pensais que les tokens servaient à faire que l'outil de design dessine les choses correctement. Ce n'est pas le cas. Les tokens servent à décrire les décisions derrière ce qui est dessiné.

Un bouton dans un outil de design est toujours un rectangle et du texte. Avec les tokens, le rectangle ne stocke pas #2563EB. Il stocke une référence : fill → color.primary. La géométrie est la même. Ce qui a changé, c'est que le fichier de design porte maintenant la raison, pas seulement le résultat.

Un composant ne se lie pas à une valeur brute. Il se lie à un token sémantique, qui pointe vers un primitif. Change le primitif, et tout en aval suit. C'est tout l'intérêt de la hiérarchie. Un changement en haut se propage partout.

Ça compte quand le design passe au code. Sans tokens, le générateur de code fait de l'ingénierie inverse sur les pixels. Il voit un rectangle bleu et écrit background: #2563EB. Avec les tokens, il lit color.primary et écrit background: var(--color-primary). Le code généré ressemble à quelque chose qu'un développeur écrirait, pas à un dump de pixels.

Les tokens ne suffisent pas

Un fichier JSON plein de tokens te dit les valeurs. Il ne te dit pas pourquoi ces valeurs existent, quand les utiliser, ou quand ne pas le faire. Tu ne peux pas exprimer « utilise primary seulement pour le CTA principal » dans un fichier tokens.json.

C'est le vide que DESIGN.md remplit. Il est sorti de Google Stitch, l'outil de design IA de Google, et a été open-sourcé en avril 2026 sous Apache 2.0. Le pitch, c'est un fichier, à la racine de ton projet, qui donne à un agent IA une compréhension persistante de ton design system.

Un fichier DESIGN.md a deux couches. Le haut, c'est du YAML front matter : tes tokens, écrits comme des valeurs structurées. Couleurs, typographie, espacement, coins arrondis, composants. En dessous, c'est de la prose markdown qui explique à quoi servent les tokens et comment les appliquer.

Les tokens donnent à un agent des valeurs exactes. La prose lui dit pourquoi ces valeurs existent.

Un composant bouton dans DESIGN.md ressemble à ça :

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px

La syntaxe de référence {colors.tertiary} vient du W3C Design Tokens Format Module. Change colors.tertiary une fois, et le bouton se met à jour partout où il est référencé. Le même standard que les outils de design comme Penpot utilisent nativement.

Huit sections

Un DESIGN.md a huit sections, dans un ordre fixe :

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

La section Do's and Don'ts, c'est là où la prose gagne sa place. « Ne jamais utiliser de drop shadows sur les cards. » « Toujours utiliser la sentence case pour les labels de boutons. » Ce sont des contraintes que les tokens purs ne peuvent pas exprimer. Un fichier de tokens JSON dit quelles sont les valeurs. DESIGN.md dit quoi faire avec elles et quoi éviter.

Pourquoi ça a pris

Il se trouve à la racine de ton repo à côté de README.md et CLAUDE.md / AGENTS.md. Les agents lisent déjà le markdown depuis la racine du projet. README.md explique le projet aux humains. CLAUDE.md et AGENTS.md disent aux agents comment se comporter. DESIGN.md leur dit à quoi l'UI devrait ressembler.

Le repo awesome-design-md sur GitHub, une collection de fichiers DESIGN.md prêts à l'emploi extraits de vrais sites en production, a dépassé 58 000 étoiles en quelques semaines après le lancement. Un taux de fork de 12,6 %, ce qui signifie qu'environ 1 personne sur 8 qui l'a trouvé a copié un fichier dans son propre projet. Ce n'est pas du bookmarking. C'est de l'adoption.

Tu n'as pas besoin d'en écrire un de zéro. Il existe des catalogues. getdesign.md a plus de 300 analyses DESIGN.md de vrais sites en production. Open Design fournit 151 packages de design system. designmd.app en indexe 461. Tu en choisis un proche de ta marque et tu l'adaptes.

La spec est encore alpha. Les valeurs de couleur sont en sRGB uniquement. Les formats à gamut large comme Oklch et Display P3, tous deux supportés par le standard W3C, ne sont pas encore dans DESIGN.md. Le CLI peut exporter vers Tailwind v3/v4 et le format DTCG du W3C, donc les tokens s'intègrent à ton pipeline existant.

Où les outils de design s'intègrent

DESIGN.md est la source de vérité. Les outils de design, c'est où tu appliques les tokens pour faire des écrans. Penpot et Figma sont deux exemples, et il y en a d'autres. Ils prennent des approches différentes du même concept.

Penpot est le premier outil de design à intégrer nativement le W3C Design Tokens Format Module. Le même standard dont les références de tokens de DESIGN.md s'inspirent. Dans Penpot, les tokens vivent dans des sets, qui sont des collections de tokens liés. Tes foundations vont dans un set : couleurs de base, valeurs d'espacement, rayons. Tes tokens sémantiques vont dans un autre : primary, success, error. Tu combines des sets en thèmes pour différents contextes. Light est un thème. Dark est un thème. Light et dark ne sont pas des design systems différents, ce sont des thèmes différents appliqués aux mêmes noms de tokens.

Parce que Penpot parle le format W3C nativement, tes tokens s'exportent au format standard. Pas de couche de traduction.

Figma prend une approche différente. Figma Variables est l'implémentation native par Figma du concept de tokens. Figma utilise des collections là où Penpot utilise des sets, et des modes là où Penpot utilise des thèmes. Une collection Figma contient des variables liées, et les modes stockent des valeurs parallèles pour différents contextes. L'aliasing construit la hiérarchie primitif → sémantique → composant : un token sémantique comme text-primary pointe vers un primitif comme gray-900, et changer le primitif met à jour tout en aval.

La différence, c'est que les variables de Figma utilisent un format propriétaire. Sortir des tokens de Figma au format standard W3C nécessite des plugins comme Tokens Studio. Penpot exporte le W3C nativement. Les deux implémentent le même concept. L'un parle le standard, l'un parle son propre dialecte.

Le point n'est pas l'outil que tu utilises. Le point, c'est que les tokens, quelle que soit la façon dont l'outil les stocke, doivent remonter à la même source de vérité : ton design system, encodé dans DESIGN.md.

Design to Code

C'est là que les pièces se connectent.

L'ancien handoff était : tu conçois dans un outil, tu exports un fichier, tu le transmets à un développeur, tu espères qu'il lit la spec correctement. Le développeur fait l'ingénierie inverse du design à partir des pixels et devine l'intention.

Le nouveau handoff est : tu encodes ton design system dans DESIGN.md. Tu conçois dans un outil en utilisant les tokens. Ton agent IA lit le DESIGN.md et génère du code de production qui utilise les mêmes noms de tokens.

Design system → DESIGN.md → AI agent → production code

L'agent obtient les valeurs exactes depuis les tokens YAML. Il obtient les règles depuis la prose. Il n'a pas à deviner si un rectangle bleu est le bouton primaire, parce que le DESIGN.md dit que button-primary utilise colors.tertiary. Le code généré utilise var(--color-tertiary), pas une valeur hex codée en dur.

En pratique, le flux va dans les deux sens. Un nouveau projet commence par les tokens. Tu définis tes tokens, tu écris le DESIGN.md, et tu laisses ton agent IA lire le DESIGN.md depuis le repo. L'agent télécharge ensuite les tokens vers l'outil de design via son CLI ou MCP. Penpot importe le format W3C nativement. Figma a besoin d'un plugin comme Tokens Studio. L'outil de design et l'agent lisent la même source.

Un projet existant va dans l'autre sens. Tu décomposes le design actuel en tokens, tu standardises le nommage, et tu écris un DESIGN.md à partir d'eux. Ensuite tu télécharges ces tokens vers l'outil de design. Si le projet n'a pas du tout de design, juste du code, l'agent IA peut lire la codebase actuelle, extraire le frontend, et déplacer le design dans l'outil de design. À partir de là, l'outil de design et la codebase partagent la même source.

La connexion entre l'outil de design et l'agent passe par MCP, ou par le CLI de l'outil s'il en a un. pen.dev démarre un serveur MCP local auquel les deux côtés se connectent.

pencil.dev (maintenant pen.dev)

pen.dev va plus loin en fusionnant l'outil de design et l'éditeur de code dans un seul environnement. C'est un canvas de design qui vit à l'intérieur de ton IDE, pas une application séparée. Les fichiers de design (.pen) se trouvent dans ton repo à côté de ton code. Git les suit. Tu branches et merges les designs de la même façon que tu branches et merges le code.

Quand pen.dev tourne, il démarre un serveur MCP local. Ton agent IA, qu'il s'agisse de Claude Code, Cursor, Codex ou OpenCode, se connecte via MCP et peut lire et modifier les fichiers de design. Les variables dans pen.dev se mappent aux custom properties CSS. Tu conçois visuellement, l'agent génère du code, et les deux côtés lisent les mêmes tokens.

La communauté a construit des outils autour de ça. Il existe un plugin Claude Code appelé pencil-atelier qui extrait le langage visuel d'un fichier .pen et l'écrit dans un design.md à la racine du projet. À partir de là, chaque passe de génération de design et de code lit le même contrat. Pas de re-briefing manuel entre les sessions.

Ce qui n'est pas encore résolu

Atlassian a testé DESIGN.md en production et a trouvé qu'il charge tout d'un coup, pas à la demande. Comparé à un serveur MCP qui récupère le contexte par composant, DESIGN.md utilisait environ 92 % de tokens en plus et avait 2,7x plus de variance entre les exécutions. C'est un snapshot portable, pas un remplacement pour un pipeline complet de design system. La spec est alpha. Les outils sont encore bruts.

Ce qui fonctionne, c'est la forme. Tu encodes tes décisions de design une fois, dans un format que les humains comme les agents peuvent lire. Tu conçois dans un outil qui utilise les mêmes tokens. Ton agent lit le même fichier et génère du code avec les mêmes noms. La partie qui est remplacée, c'est la couche de traduction, celle qui était autrefois une personne avec un fichier Figma et une supposition.