Qu'est-ce que DESIGN.md ? Format, contenu et erreurs courantes

DESIGN.md a vu le jour chez Google Labs comme format supportant Stitch, son outil de génération d'UI. Google a rendu la spécification open source, et la spec réside désormais sur GitHub. Elle s'est rapidement diffusée au-delà de Google : Atlassian a publié un retour d'expérience sur le test de contextes de design portables en pratique, et un écosystème de catalogues s'est développé autour.

L'extension .md signifie simplement markdown. Le fichier n'a pas de syntaxe spéciale, pas de schéma de validation, ni d'étape de build. C'est intentionnel : un agent le lit comme n'importe quel autre fichier de votre dépôt.

Un agent de code chargé de construire une UI doit puiser ses valeurs visuelles quelque part. En l'absence de source, il utilise les valeurs par défaut des bibliothèques, ce qui explique pourquoi les produits créés par IA convergent vers un même aspect. Vous pouvez fournir des valeurs dans un prompt, mais les prompts appartiennent à une conversation, et les conversations s'estompent à mesure qu'elles s'allongent.

Un fichier, lui, ne s'estompe pas. C'est tout le principe du mécanisme, et tout le reste du format en découle.

Plutôt que de faire des suppositions, nous avons procédé à un échantillonnage. Nous avons extrait 299 fichiers DESIGN.md situés à la racine de dépôts via la recherche de code GitHub et analysé leur contenu. Le premier résultat a été surprenant et recadre tout le reste.

Parmi ces 72 fichiers de design visuel authentiques, le constat est constant. Le fichier médian compte 1 337 mots sur 263 lignes ; ce ne sont donc pas des ébauches : les auteurs y consacrent un effort réel. Ils se concentrent sur les trois mêmes sections et en oublient les quatre mêmes.

La couleur et la typographie sont quasi universelles. Le rayon, l'élévation, l'iconographie et l'accessibilité sont rares. Et une omission est plus critique que toutes les autres, car elle reste invisible jusqu'à ce que quelqu'un active un interrupteur.

Sur les 72 fichiers de design visuel analysés, 50 ne contiennent aucun mode sombre : pas de bloc .dark, pas de prefers-color-scheme, pas de second jeu de valeurs. Soit 69 %.

C'est la lacune la plus lourde de conséquences dans la pratique actuelle, et elle échoue silencieusement. Tout semble correct en mode clair. Puis l'utilisateur bascule le thème et l'agent doit inventer chaque valeur sombre à la volée : un arrière-plan jamais choisi, un premier plan dont le contraste n'a jamais été vérifié, une couleur d'accentuation qui s'efface car personne n'a augmenté son chroma pour un fond sombre.

## Color

### Light
--background: oklch(0.98 0.006 85)
--foreground: oklch(0.22 0.014 85)
--card:       oklch(1 0 0)
--muted-foreground: oklch(0.48 0.012 85)
--primary:    oklch(0.52 0.13 152)
--border:     oklch(0.90 0.008 85)

### Dark
--background: oklch(0.17 0.010 85)   /* not pure black */
--foreground: oklch(0.95 0.006 85)   /* not pure white */
--card:       oklch(0.22 0.010 85)   /* raised, not shadowed */
--muted-foreground: oklch(0.70 0.010 85)
--primary:    oklch(0.68 0.16 152)   /* higher chroma to survive the dark ground */
--border:     oklch(0.30 0.010 85)

Seulement 6 % des fichiers analysés utilisent OKLCH. Le passage à ce format en vaut la peine ici spécifiquement parce que son canal de luminosité est perceptuellement uniforme, vous permettant ainsi de modifier une teinte sans avoir à revérifier chaque paire de contraste.

La décision la plus cruciale du fichier est de nommer par *rôle* plutôt que par teinte. --primary indique à un agent où placer la valeur ; --blue-600 ne le fait pas. Les rôles lui permettent d'appliquer correctement votre système dans des situations que vous n'aviez pas anticipées, et ils survivent à un rebranding.

86 % des fichiers analysés n'utilisent aucun nom de rôle sémantique. Ils listent des codes hexadécimaux ou nomment les couleurs par teinte. C'est là toute la différence entre un fichier qu'un agent peut appliquer à un composant que vous n'avez jamais décrit et un fichier dont il ne peut que copier les valeurs. C'est la couche de tokens sémantiques qui effectue ici le travail réel.

Nommez les familles, les graisses, l'approche (tracking) et les paliers de l'échelle. L'erreur classique est d'écrire *une police serif pour les titres, une sans-serif pour le corps*. C'est une instruction que l'agent doit résoudre, et il le fera différemment à chaque fois.

## Typography

Heading: "Fraunces", serif — 600, tracking -0.02em
Body:    "Inter", sans-serif — 400, line-height 1.6
Mono:    "JetBrains Mono" — 400, tabular figures in tables

Scale: 0.8125 / 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem
H1 uses 3rem at 1.05 line-height; body copy never exceeds 68ch.

Une échelle d'espacement, un rayon qui varie selon la taille de l'élément, et deux ou trois niveaux d'élévation cohérents avec une source lumineuse. Le rayon n'est couvert que par 21 % des fichiers et l'élévation par 26 %, ce qui explique pourquoi tant d'UI générées appliquent un angle de 0.5rem sur chaque élément, quelle que soit sa taille.

## Spacing
Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96px
Section rhythm: 96px desktop, 64px mobile.

## Radius
sm 0.25rem (inputs) · md 0.5rem (buttons) · lg 0.875rem (cards) · xl 1.25rem (modals)

## Elevation
0 flush — use a border, no shadow
1 cards — 0 1px 2px rgb(0 0 0 / 0.06)
2 dropdowns — 0 4px 12px rgb(0 0 0 / 0.08)
Dark mode: raise the surface, do not deepen the shadow.

Les tokens indiquent à un agent quelles valeurs utiliser. Ils ne disent rien sur la marche à suivre face à un composant que votre fichier n'a jamais mentionné. Les motifs et les interdictions comblent cette lacune ; ils font la différence entre un fichier qui contraint le résultat et un fichier qui se contente de le colorer.

76 % des fichiers ne mentionnent aucune interdiction et 57 % aucun motif. Ce sont les deux sections les plus simples à rédiger et les plus souvent absentes.

## Motifs
- Hairline rules separate sections; no boxed cards on marketing pages.
- Numerals are tabular everywhere they can be compared.
- One accent per screen. If two things compete, one becomes muted.

## Don't
- No gradient text, ever.
- No shadow on a flush surface — use --border.
- Never hardcode a hex. If a role is missing, add the role.

Couvrez les primitives qui portent le plus d'identité : boutons, champs de saisie et cartes, avec leurs différents états. Vous n'avez pas besoin de lister chaque composant. L'iconographie est la section la plus simple du fichier et la plus rare en pratique (10 %) : nommez la bibliothèque d'icônes, l'épaisseur du trait, les paliers de taille et ajoutez une ligne sur le traitement des images.

Au-delà des sections manquantes, un mode d'échec apparaît dans plus de la moitié du corpus : l'utilisation d'un adjectif là où une valeur est attendue.

54 % des fichiers analysés contiennent au moins un adjectif vague en guise de décision. Les plus fréquents étaient *clean* (39 % des fichiers), *modern* (36 %) et *professional* (22 %), suivis de *generous whitespace*, *elegant* et *beautiful*. De plus, 44 % ne contiennent aucune valeur concrète d'espacement ou de taille dans tout le fichier.

1. Des adjectifs au lieu de valeurs. Le défaut le plus courant, présent dans plus de la moitié des fichiers.
2. Mode sombre omis. Dans 69 % des cas, et l'échec est silencieux.
3. Couleurs nommées par teinte plutôt que par rôle. Dans 86 % des cas, et cela pose problème dès que l'agent rencontre un composant que vous n'avez pas décrit.
4. Aucune interdiction. Dans 76 % des cas. Les interdictions sont suivies plus rigoureusement que les préférences.
5. Une section qui dit « utilisez votre jugement ». Pire que l'absence de section, car elle redonne exactement la discrétion que le reste du fichier tentait de supprimer.

Placez-le à la racine du dépôt, à côté de AGENTS.md. La racine est cruciale : un DESIGN.md imbriqué dans docs/ est un document pour les humains, alors que les agents qui recherchent cette convention regardent la racine.

Référencez-le ensuite dans vos instructions d'agent en une seule ligne, afin qu'il soit découvert plutôt que trouvé par hasard. Il est le complément de ces fichiers et non leur concurrent : les quatre fichiers remplissent des fonctions différentes.

# AGENTS.md

## Design
Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

AGENTS.md est la convention plus large pour les instructions d'agent et est lue par un nombre croissant d'outils. DESIGN.md contient le contrat visuel ; AGENTS.md y renvoie.

C'est la partie que tous les autres guides oublient. Un DESIGN.md ne vaut que par l'interface qu'il produit, et les sections ci-dessus ne sont pas une illustration. Elles sont la forme sérialisée du kit ci-dessous.

Si vous l'écrivez à la main, les deux sections sur lesquelles vous devez vous forcer sont le mode sombre et les interdictions. Le corpus montre sans ambiguïté que ce sont celles que les gens sautent, et ce sont elles qui déterminent si le fichier impose réellement des contraintes.