Qu'est-ce que design.md pour les agents de codage ?

Je m’appelle Dora. La semaine dernière, j’ai demandé à Claude Code d’ajouter trois nouveaux écrans à un projet personnel. Dès le deuxième écran, le rayon des boutons avait dérivé, la police des titres avait subtilement changé, et le gris « secondaire » était un gris différent. Même structure de prompt. Même modèle. Même session. Le résultat avait tout simplement arrêté de se soucier de ce qui précédait.

C’est cette friction que design.md pour les agents de codage cherche à éliminer. Il s’agit d’un fichier markdown ordinaire qui contient votre système de design dans une forme qu’un agent IA peut lire à chaque fois qu’il génère de l’interface — non pas comme un prompt ponctuel, mais comme un contexte persistant. Stitch le lit. Claude Code le lit. Cursor le lit. Tout autre outil qui récupère des fichiers de contexte depuis la racine d’un dépôt le lit également.

Ce qu’est design.md et pourquoi Google Labs l’a publié

Format de fichier et rôle dans le système de design

Un fichier DESIGN.md est composé de deux couches empilées dans un seul document. La première est un en-tête YAML — couleurs, typographie, espacement, coins arrondis, composants — rédigé sous forme de tokens structurés. En dessous se trouve une prose markdown qui explique à quoi servent les tokens et comment les utiliser. Les tokens donnent à un agent des valeurs précises. La prose lui explique pourquoi ces valeurs existent.

Voici à peu près à quoi ressemble l’en-tête, extrait de la spécification officielle DESIGN.md sur GitHub :

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

En dessous, ## Vue d’ensemble, ## Couleurs, ## Typographie en markdown simple. L’ordre des sections est fixe — Vue d’ensemble, Couleurs, Typographie, Mise en page, Élévation & Profondeur, Formes, Composants, À faire et à ne pas faire. Les sections peuvent être omises, mais celles qui sont présentes doivent apparaître dans cet ordre. Les titres de section dupliqués constituent une erreur et rejettent le fichier.

La syntaxe de référence des tokens provient du W3C Design Tokens Format Module — des chemins entre accolades comme {colors.primary}. Les références doivent pointer vers des valeurs primitives (pas des groupes), sauf dans la section des composants où des références composites vers des tokens typographiques sont autorisées. Les valeurs de couleur sont uniquement en hexadécimal SRGB dans la spécification actuelle. Display P3 et Oklch — tous deux pris en charge par la spécification stable W3C DTCG 2025.10 — ne sont pas encore supportés par DESIGN.md, ce que le dépôt signale ouvertement avec son marqueur version: alpha. Utile à savoir si vous maintenez des tokens à gamme étendue.

Le format est livré avec une CLI — @google/design.md sur npm. npx @google/design.md lint exécute sept règles contre un fichier analysé. Les deux que je rencontre le plus souvent : broken-ref (niveau erreur) détecte les références de tokens qui ne se résolvent pas, et contrast-ratio (avertissement) vérifie les paires backgroundColor/textColor des composants par rapport au minimum 4,5:1 de WCAG AA. Trois autres — missing-primary, orphaned-tokens, et les règles structurelles — font remonter les problèmes que la plupart des équipes introduisent dans la semaine suivant la modification du fichier. La CLI dispose également de diff (régressions au niveau des tokens entre versions) et export (config Tailwind v3, CSS @theme Tailwind v4, ou JSON W3C DTCG).

Pourquoi le contexte visuel persistant est important pour les agents de codage

Le problème est simple. Un agent qui génère de l’interface n’a aucune mémoire de votre système de design sauf si vous lui donnez quelque chose de structuré à lire. Vous pouvez décrire votre palette dans un prompt, obtenir un bouton en retour, puis demander une carte et regarder la logique d’espacement se réinitialiser. Le modèle n’est pas mauvais pour écrire du code. Il n’a simplement pas d’ancre.

design.md est cette ancre. Stitch le passe comme contexte à chaque requête de génération. Claude Code et Cursor le récupèrent de la même façon qu’ils récupèrent CLAUDE.md ou AGENTS.md — un fichier à la racine du dépôt que l’agent lit avant de répondre. La présentation de Google dans l’annonce open-source est que cela permet aux agents de « savoir exactement à quoi sert une couleur » plutôt que d’en deviner l’intention depuis un prompt.

J’ai testé cela sur les deux projets. Procédure : déposer un DESIGN.md à la racine, régénérer les cinq mêmes écrans qui avaient dérivé auparavant (page d’accueil, tarification, inscription, tableau de bord, paramètres), puis compter les violations de tokens par rapport à l’en-tête. Avec le fichier présent, Claude Code a produit 5/5 écrans en utilisant exactement les valeurs hex primaire et tertiaire ainsi que la valeur rounded.sm déclarée. Cursor a produit 4/5 — le tableau de bord continuait de remplacer rounded.sm (4px) par rounded.md (8px) sur les cartes, ce que la prose de DESIGN.md n’avait pas explicitement interdit. Ajouter une ligne « À faire et à ne pas faire » — « les coins des cartes utilisent rounded.sm, jamais rounded.md » — a résolu le problème lors de la régénération suivante.

Le vrai problème qu’il résout dans la génération d’interface par IA

Cohérence entre les écrans et les itérations

Ce qui a cassé dans la session précédente n’était pas la qualité d’un écran en particulier. Chaque écran individuel avait l’air bien. L’écran deux ne savait pas ce que l’écran un avait décidé. Chaque génération partait d’une interprétation légèrement différente de « votre marque ».

C’est ce mode d’échec que design.md cible. Non pas « rendre l’interface plus belle » — la rendre identique d’une génération à l’autre. Les tokens sont normatifs. Quand l’en-tête dit tertiary: "#B8422E", l’agent n’a aucune marge pour l’interpréter comme « un orange chaud ». C’est cette valeur hexadécimale ou c’est faux, et le lint le dira.

Pour les workflows à haute fréquence — cinq, dix, vingt écrans par semaine avec quelqu’un qui les maintient — cela compte plus que la qualité de la première sortie. Une incohérence par écran à grande échelle devient un travail de nettoyage. Les tokens de design des agents de codage, définis une fois dans un fichier, éliminent ce travail de nettoyage avant qu’il ne commence.

Pourquoi la prose plus les tokens est plus forte que les tokens seuls

J’ai failli ignorer cette partie. Pourquoi écrire des paragraphes de « Boston Clay est le seul moteur pour l’interaction » quand la valeur hexadécimale est déjà dans le YAML ?

Parce que l’agent utilise la prose pour prendre des décisions que les tokens ne couvrent pas. Les tokens disent que tertiaire est #B8422E. La prose dit que cette couleur est réservée à l’interaction uniquement — pas pour les accents décoratifs, pas pour les titres. Quand un prompt est ambigu (« ajouter un badge de notification »), la prose décide si le badge prend la couleur d’interaction ou un neutre. Dans mon exécution Cursor ci-dessus, la contrainte de prose manquante était exactement la raison pour laquelle le tableau de bord avait dérivé.

La même logique s’applique aux À faire et à ne pas faire — des garde-fous explicites comme « n’utilisez jamais d’ombres portées sur les cartes » ou « utilisez toujours la casse de phrase pour les libellés de boutons ». Les contraintes négatives portent un poids que les tokens purs ne peuvent pas exprimer. C’est une spécification de design pour les agents, pas un fichier CSS.

Le format n’est pas lié à Stitch. La spécification est Apache 2.0, la CLI est sur npm, l’export DTCG signifie que les tokens s’écoulent dans tout outil qui lit le standard W3C, et la communauté est déjà en mouvement. La collection awesome-design-md de VoltAgent de fichiers DESIGN.md inspirés de marques a dépassé 71 000 étoiles GitHub en quelques semaines après le lancement, et le topic GitHub design-md liste maintenant des outils d’extraction, des extensions Chrome et des registres SKILL.md compagnons complètement extérieurs à Google. L’adoption est ce qui vous dit qu’un format est réel.

Qui devrait s’intéresser à design.md

Pour être honnête sur les limites, parce que design.md n’est pas adapté à tous les cas.

Il mérite sa place si :

Vous générez de l’interface avec des agents de codage au moins chaque semaine, sur plus d’un écran
Vous avez un système de design — même minimal — que vous souhaitez préserver d’une génération à l’autre
Vous travaillez avec plus d’un agent ou outil et vous voulez le même contexte de marque dans tous
Vous en avez assez de coller « rappelle-toi que notre palette est X, Y, Z » dans chaque prompt

Il ne mérite pas sa place si :

Vous générez des maquettes ponctuelles et les jetez
Votre « système de design » est ce que l’agent produit cette fois-ci
Vous êtes dans un workflow piloté par Figma avec un pipeline DTCG mature via Style Dictionary ou similaire — design.md est plus léger que ce que vous avez, et vous régresseriez
Vous avez besoin de couleurs à gamme étendue (Display P3, Oklch) aujourd’hui — la spécification alpha actuelle est SRGB uniquement

Pour les équipes produit natives à l’IA qui utilisent design.md en parallèle d’autres fichiers de workflow IA (CLAUDE.md, AGENTS.md), il s’intègre proprement. Un fichier markdown par préoccupation. Pas d’étape de build. Pas de schéma JSON à combattre. Le coût d’essai est d’un fichier à la racine du dépôt et d’une commande lint.

Pour les plateformes construisant des surfaces de génération pilotées par des agents — y compris les couches de génération IA unifiées qui acheminent les requêtes entre plusieurs modèles et ont besoin que le contexte de marque se maintienne à chaque appel — design.md est ce que l’écosystème a de plus proche d’un contrat portable entre une marque et un agent. Selon l’annonce de Google Labs, le format a été conçu spécifiquement pour être exportable et importable entre les outils. Cette portabilité est l’essentiel.

FAQ

À quoi sert design.md ?

C’est un fichier markdown qui donne aux agents de codage un contexte persistant sur un système de design — couleurs, typographie, espacement, composants, plus une prose expliquant comment les appliquer. L’agent le lit chaque fois qu’il génère de l’interface, de sorte que le résultat reste cohérent d’un écran à l’autre et d’une session à l’autre sans que vous ayez à respécifier les règles de la marque dans chaque prompt.

Est-il uniquement pour les workflows Google Stitch ?

Non. Le format est né dans Stitch mais Google a ouvert la spécification sous Apache 2.0. Tout outil IA qui lit des fichiers de contexte — Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI — peut l’utiliser. La CLI exporte vers une config Tailwind, des variables CSS ou du JSON W3C DTCG, de sorte que les tokens s’écoulent également dans les outils non-agents.

Pourquoi l’interface générée par IA a-t-elle besoin d’un fichier de système de design ?

Parce que les modèles n’ont aucune mémoire de votre marque entre les générations. Sans un fichier de système de design IA structuré, chaque prompt réinterprète votre langage de design depuis zéro. Avec un tel fichier, les tokens agissent comme des contraintes strictes et la prose couvre les jugements de valeur. La différence se manifeste le plus clairement à grande échelle — cinq écrans générés avec design.md maintiennent leur style ; cinq écrans générés sans lui dérivent.

Quelles équipes devraient l’expérimenter en premier ?

Les équipes qui génèrent déjà de l’interface avec des agents de codage chaque semaine. Les développeurs indépendants et les petites équipes produit utilisant Claude Code ou Cursor obtiennent le retour le plus rapide — déposez le fichier, régénérez, constatez la cohérence. Les grandes organisations avec des pipelines Figma + Style Dictionary matures devraient traiter design.md comme un complément, pas un remplacement : utilisez-le pour donner aux agents un sous-ensemble digestible du système existant.

Conclusion

design.md n’est pas un format de fichier révolutionnaire. C’est un fichier markdown avec du YAML en haut. C’est justement là l’idée — le format que les LLM lisent le mieux est celui sur lequel ils ont été le plus entraînés, et c’est le texte brut.

Ce qu’il fait réellement, c’est déplacer la question de « comment est-ce que je décris mon design dans ce prompt » vers « où vit mon design pour que chaque agent puisse le lire ». Un fichier, un emplacement, chaque outil qui le récupère obtient la même réponse. Une chose de moins à respécifier. Ça paraît petit. Ça s’accumule vite.

Je l’ai dans deux projets depuis une semaine. Ça fonctionne. Sur le long terme — que les équipes maintiennent ces fichiers avec la même rigueur qu’un vrai système de design, ou qu’ils se dégradent comme les README se dégradent — c’est encore à vérifier. Lancez-le sur un de vos projets. Ça vous en apprendra plus que tout ce que je pourrais dire.

Articles précédents :