Le 21 avril 2026, Google Labs a publié DESIGN.md, un fichier Markdown qui permet aux agents IA de respecter l’identité visuelle d’une marque. En quelques semaines, le projet a dépassé les 70 000 étoiles sur GitHub. Des centaines d’équipes l’ont adopté.
3 erreurs reviennent pourtant. Elles transforment cet outil en placebo de cohérence.
Sur le papier, c’est propre. Dans la pratique, la greffe ne prend pas toujours. 3 erreurs reviennent, et elles n’ont rien à voir avec la syntaxe.
Le dépôt communautaire awesome-design-md propose plus de 69 modèles prêts à copier : Stripe, Linear, Notion, Vercel. Vous téléchargez un fichier fonctionnel en 30 secondes.
Mais c’est là que ça dérape.
DESIGN.md est une spécification ouverte par Google Labs le 21 avril 2026, sous licence Apache 2.0. Ce fichier Markdown, placé à la racine d’un projet, donne aux agents IA comme Claude Code, Cursor ou Copilot les règles visuelles exactes d’une marque. Couleurs, typographie, espacements, composants : l’IA cesse de deviner et applique un cadre cohérent.
L’erreur du copier-coller aveugle
Un fichier DESIGN.md n’est pas un document de charte graphique classique. C’est un contrat de contraintes que l’agent de codage lit avant de générer le moindre composant. Il décrit les couleurs, les espacements, la typographie, les états interactifs et les règles d’accessibilité dans un format que la machine peut appliquer sans interprétation.
La confusion la plus fréquente consiste à y mettre des intentions (« moderne », « épuré ») au lieu de valeurs mesurables. Un agent ne sait pas ce qu’est « moderne ». Il sait ce qu’est un rayon de bordure de 8px et une police de corps à 16px.
Première tentation : prendre le modèle Stripe, changer deux couleurs, croire que le travail est fait. J’ai vu cette approche produire des résultats catastrophiques sur des projets réels.
Pourquoi ? Un DESIGN.md de qualité encode des décisions de design qui ne se transfèrent pas d’une marque à l’autre. Le modèle Stripe suppose une densité d’information et une hiérarchie visuelle pensées pour un dashboard de paiement. Appliquez-le à un site de recettes de cuisine : l’interface semble perdue, trop clinique. Les espacements sont conçus pour des tableaux de données, pas pour des listes d’ingrédients.
Le fichier ne contient pas que des tokens. Il contient une intention esthétique, et cette intention dépend du contexte métier. Copier sans comprendre, c’est reproduire les symptômes d’une autre marque, pas les vôtres.
Ce phénomène n’est pas propre au design. Sur Windows, un presse-papiers saturé peut bloquer la fonction copier-coller jusqu’à ce qu’on purge l’historique. Le parallèle est frappant : copier sans discernement encombre le système, et l’agent se retrouve à appliquer des règles inadaptées au lieu de repartir d’une intention claire. Le presse-papiers de votre DESIGN.md, c’est votre jugement de designer, et il faut le vider avant chaque nouveau projet.
Ce que les modèles ne disent pas
Un modèle communautaire est un point de départ, pas une destination. Il vous fait gagner une heure sur la structure. Il vous en coûtera trois si vous ne l’adaptez pas en profondeur.
- La palette de couleurs doit refléter votre secteur, pas celui de Stripe.
- Les règles de composants doivent correspondre à vos interactions réelles.
- La section Agent Prompt Guide doit décrire vos cas limites, pas ceux d’une plateforme de paiement.
Comment DESIGN.md s’intègre-t-il avec Claude Code ?
Vous enregistrez le fichier à la racine du projet et ajoutez une référence explicite dans CLAUDE.md. Quelque chose comme « Always refer to DESIGN.md when generating UI components. Use only colors, fonts, and spacing defined there. » À partir de ce moment, Claude lit DESIGN.md comme contexte persistant et applique les règles à chaque composant généré. Le setup prend moins de 5 minutes.
Le fichier fantôme qui n’est jamais lu
Les voici, dans l’ordre où un agent les consomme :
- Palette de couleurs avec rôles sémantiques (primaire, surface, erreur, succès).
- Échelle typographique (tailles, graisses, hauteurs de ligne).
- Espacements sur une base de 4 ou 8 pixels.
- Rayons de bordure et ombres autorisés États interactifs (survol, focus, désactivé, chargement).
- Règles d’accessibilité (contraste minimum, focus visible).
- Bibliothèque de composants de référence (shadcn/ui, Radix, autre).
- Interdictions explicites (dégradés, ombres multiples, polices fantaisie).
Et quand il improvise sur 8 points à la fois, le résultat ressemble à 8 personnes différentes qui auraient codé le même écran.
Deuxième erreur, plus sournoise. Vous écrivez un DESIGN.md impeccable. Vous le placez à la racine.
Vous lancez Cursor. Et rien ne change.
Les agents ne lisent pas automatiquement tous les fichiers du dépôt. Claude Code, Cursor et Copilot ont chacun leur mécanisme de découverte contextuelle. Sans référence explicite, le fichier reste orphelin.
Le problème du fichier fantôme est bien connu des utilisateurs de Windows comme de macOS. Sur une clé USB, des fichiers « fantômes » apparaissent parfois : ils existent dans l’index mais pas sur le disque, et il devient impossible de les supprimer. Un DESIGN.md non référencé se comporte de la même manière : il existe dans le dépôt, mais pas dans le contexte de l’agent. La solution, dans les deux cas, passe par une action explicite : purger l’index ou déclarer le fichier dans les instructions.
La solution la plus fiable : mentionner explicitement DESIGN.md dans vos instructions de projet, ou utiliser le CLI fourni par Google. La commande npx @google/design.md lint DESIGN.md valide la structure et vérifie les ratios de contraste WCAG AA. Un fichier validé mais jamais lu ne sert à rien.
La vérification qui change tout
Avant de lancer une génération d’interface, demandez à l’agent de citer les couleurs qu’il va utiliser. S’il ne peut pas les nommer, il n’a pas lu le fichier. Cette vérification prend 10 secondes et évite des heures de débogage visuel.
Puis-je utiliser DESIGN.md sans Google Stitch ?
Oui, et c’est le point clé de l’annonce du 21 avril 2026. La spec est ouverte sous licence Apache 2.0 : vous pouvez écrire DESIGN.md à la main dans n’importe quel éditeur, le committer sur GitHub et le faire consommer par Claude Code, Cursor, Copilot ou tout autre agent compatible. Stitch le génère automatiquement, mais ce n’est pas un prérequis.
Le piège de la sur-spécification
Pour créer le fichier, partez de l’existant. Ouvrez trois écrans représentatifs de votre produit, relevez les valeurs réellement utilisées (couleurs, tailles, espacements), et ne gardez que celles qui reviennent au moins 2 fois. Le reste part à la poubelle.
Écrivez ensuite le fichier en anglais ou en français, peu importe, mais avec des valeurs numériques et des noms de tokens stables. Un agent qui lit --color-primary: #2563eb appliquera la bonne couleur. Un agent qui lit « bleu de la marque » cherchera au hasard.
Troisième erreur : écrire un DESIGN.md de vingt sections qui décrit chaque état de chaque composant. Le fichier devient si rigide que l’IA ne peut plus faire le moindre choix créatif.
Résultat : des interfaces mécaniques, sans respiration, qui suivent les règles à la lettre mais oublient le produit. Un bon DESIGN.md laisse des zones de liberté. Il dit ce qui est non-négociable, pas ce qui doit être identique au pixel près.
Le piège ne touche pas que le design logiciel. En acoustique architecturale, exiger un indice d’isolation de calibre laboratoire sans évaluer les conditions réelles d’une salle de classe produit des espaces morts, étouffants, qui nuisent à la concentration au lieu de la favoriser. La leçon est identique : une spécification sans marge d’adaptation au contexte réel devient contre-productive. Un DESIGN.md qui spécifie chaque pixel est une chambre anéchoïque : techniquement parfaite, humainement invivable.
La section Agent Prompt Guide est là pour ça. Elle doit guider, pas enfermer. Si vous écrivez « toujours utiliser le bouton primaire avec un padding de 12px », vous avez transformé un guide en camisole.
La règle des 80/20
Un DESIGN.md efficace définit 80 % des cas courants et laisse flous les 20 % de cas limites. Ces zones grises permettent à l’agent d’adapter le design au contexte sans trahir la marque. Source : howaiworks.ai
=> Vous aimerez aussi : Le mode Plan dans Claude Code, Cursor, Codex et Opencode : pourquoi planifier avant de coder change tout
Qu’est-ce que DESIGN.md en termes simples ?
DESIGN.md est un fichier markdown qui décrit les règles visuelles de votre projet dans un format lisible à la fois par les êtres humains et par les agents IA. Vous le placez à la racine du projet et chaque outil compatible l’utilise pour générer des interfaces cohérentes avec votre marque. Il fait pour le design ce que README.md fait pour la documentation.
Pourquoi ça vaut quand même le coup
Le duo DESIGN.md et Claude Code fonctionne parce que les deux fichiers ne jouent pas le même rôle. CLAUDE.md décrit les conventions de code, les commandes de build, l’architecture des dossiers. DESIGN.md décrit l’apparence et le comportement visuel. Un agent qui n’a que le premier produit du code propre avec une interface incohérente.
La branche shadcn/ui illustre bien le problème. Si vous laissez l’agent choisir les variantes de boutons, il en créera cinq différentes en trois écrans. Un DESIGN.md qui liste les variantes autorisées (default, outline, ghost) et interdit les autres règle le sujet en une ligne.
Malgré ces pièges, le format a un avantage sur les alternatives. Figma vit en dehors du dépôt. Les jetons JSON n’expliquent pas l’intention. Les règles Cursor décrivent un comportement, pas un système de design.
DESIGN.md est le seul format qui combine lisibilité humaine, versionnage Git et compréhension native par les agents. C’est un pont entre le designer et la machine, pas un remplacement de l’un par l’autre.
« Ça vaut le coup » ou « ça vaut le coût » n’est pas qu’une hésitation orthographique. « Valoir le coup » signifie « valoir la peine », et c’est le calcul à faire ici : le coût d’adoption de DESIGN.md (rédaction, adaptation, maintenance) est-il justifié par le bénéfice ? Pour une équipe qui génère des interfaces via des agents, la réponse est oui.
Pour un projet ponctuel, peut-être pas. La dépense est réelle, mais elle est à la hauteur de l’enjeu : la cohérence visuelle d’un produit sur la durée.
La compatibilité avec le standard W3C Design Tokens et avec les configurations Tailwind change la donne. Vous pouvez exporter votre DESIGN.md vers un fichier tailwind.config.js, ou importer vos tokens existants. Ce n’est pas un format fermé : c’est une brique d’interopérabilité.
Questions fréquentes
Qui a créé le format DESIGN.md ?
Le format n’a pas d’inventeur unique ni de spécification officielle. Il s’est imposé par usage dans l’écosystème des agents de codage (Claude Code, Cursor, Copilot) comme complément au fichier CLAUDE.md ou AGENTS.md. Chaque équipe adapte la structure à ses besoins.
Faut-il adopter DESIGN.md sur un projet existant ?
Oui, à condition de partir de l’existant et non d’une charte idéale. Un projet qui a déjà une interface cohérente gagne surtout à documenter ses tokens réels pour éviter que l’agent n’introduise des variantes. Un projet sans cohérence gagne à fixer des règles minimales avant de laisser l’agent générer du code.
Combien de lignes doit faire un DESIGN.md efficace ?
Un fichier utile tient généralement entre 50 et 150 lignes. En dessous, il manque des invariants et l’agent improvise. Au-dessus, il devient un document que personne ne lit, ni l’humain ni la machine.
Pourquoi mon agent IA ignore-t-il mon fichier DESIGN.md ?
Les agents ne découvrent pas systématiquement tous les fichiers du dépôt. Mentionnez explicitement DESIGN.md dans vos instructions de projet, ou vérifiez que votre outil le référence dans son contexte. Une vérification simple : demandez à l’agent de citer les couleurs de votre palette avant de générer l’interface.
Un DESIGN.md copié depuis un modèle Stripe fonctionne-t-il pour mon projet ?
Un modèle encode des décisions de design liées à un contexte métier précis. Copier les couleurs ne suffit pas : il faut réécrire l’intention esthétique, les règles de composants et le guide d’agent pour qu’ils correspondent à votre produit.
Faut-il spécifier chaque composant dans DESIGN.md ?
Non. Une spécification trop rigide produit des interfaces mécaniques. Visez 80 % de cas précis et laissez 20 % de zones grises où l’agent peut adapter le design au contexte. Le guide d’agent doit orienter, pas enfermer.
DESIGN.md remplace-t-il Figma ?
Non. Figma reste un outil de conception visuelle pour les humains, qui vit en dehors du dépôt. DESIGN.md est un fichier texte versionné, lisible par les agents IA. Les deux peuvent coexister : Figma pour explorer, DESIGN.md pour contraindre la génération de code.
Les questions qui reviennent
Prenez l’exemple d’un développeur qui travaille quotidiennement avec des fichiers XML. Il explique que Chrome se contente d’afficher le texte brut, sans aucune mise en forme. Il cherche donc une extension capable de reproduire ce que proposait Internet Explorer : la coloration syntaxique, le surlignage des balises ouvrantes et fermantes, une lecture structurée. Sa demande a reçu 72 votes, ce qui montre que ce besoin de lisibilité ne concerne pas qu’une poignée d’originaux.
C’est exactement le même raisonnement qu’avec le design MD de Google. Un fichier qui n’est pas conçu pour être lu par un humain finit par être ignoré. La question n’est pas seulement d’avoir un document de référence, c’est d’avoir un document que les équipes ont envie d’ouvrir. Si l’outil n’offre aucune hiérarchie visuelle, personne ne l’utilise, et la cohérence promise reste théorique.
Autre cas intéressant : un utilisateur de Google Groups cherchait à recevoir par e-mail ses propres messages publiés sur une liste de diffusion, y compris ceux qu’il modérait. Il précise que l’option « m’envoyer un e-mail pour chaque nouveau message » ne suffit pas. Résultat : le premier message qu’il a approuvé n’est jamais arrivé dans sa boîte. Cette friction administrative, mineure en apparence, casse le flux de travail d’un modérateur.
Transposé à un système de design, c’est le piège des permissions et des notifications mal pensées. Si un contributeur ne reçoit pas de retour quand sa modification est validée, il arrête de contribuer. La cohérence d’un fichier de design ne dépend pas que de son contenu, elle dépend aussi de la mécanique qui l’entoure. Un bon fichier mal outillé reste un fichier fantôme.
Un participant à une discussion technique sur les solutions ETL résume bien le problème : il n’existe pas d’outil généraliste. La plupart des logiciels sont soit surdimensionnés, soit pas assez robustes pour la tâche. Lui s’en sort avec beaucoup de scripts Python pour ses besoins spécifiques. C’est un constat que beaucoup de développeurs partagent, et il s’applique parfaitement au design MD : un outil universel ne répond jamais aux cas particuliers.
D’ailleurs, quand Google a ouvert une partie de son outillage interne en 2011, certains sceptiques ont immédiatement pointé une stratégie d’écosystème. L’open source servirait à orienter les développeurs vers les revenus ou le recrutement de l’entreprise. Sans trancher ce débat, une chose est sûre : adopter un standard open source, c’est aussi accepter une dépendance à la feuille de route de son éditeur. C’est une réalité à intégrer avant de tout construire dessus.
- Displaying XML in the Chrome browser (CC-BY-SA 4.0)
- Good open source Video Editors? (CC-BY-SA 4.0)
- Need help to fix a broken MP4 which lacks a MOOV atom (CC-BY-SA 4.0)
- Self-Hosted alternative to Google Docs? (CC-BY-SA 4.0)
- How to receive my own Google Groups posts by e-mail? (CC-BY-SA 4.0)
=> Dans la continuité : Des sites au design moderne
DESIGN.md respecte-t-il les standards W3C pour les design tokens ?
Oui, la structure des tokens suit le W3C Design Token Community Group (DTCG). Cela signifie que vous pouvez exporter un fichier tokens.json conforme au standard ouvert et un tailwind.config.js prêt pour les projets Tailwind CSS. La spec exige également de valider les choix chromatiques contre les standards WCAG AA/AAA pour l’accessibilité.
Ce que j’en pense, perso,
Le format est bon. La spécification est propre, l’ambition est claire, et l’ouverture sous licence Apache 2.0 est un signal. Mais un fichier ne remplace pas une décision de design.
Ceux qui réussiront avec DESIGN.md ne sont pas ceux qui copient un modèle en 30 secondes. Ce sont ceux qui comprennent que le fichier encode un jugement, et que ce jugement doit être le leur.
Les études qui comptent
| github.com ↗ |
| Build a Consistent Brand With Google’s Design.md ↗ |
Ce que j’ai déjà écrit là-dessus
| L’UE va-t-elle tuer les téléphones Linux et GrapheneOS ? |
| Authentik auto-hébergé : guide pour configurer SSO et MFA open-source |
Quand la cohérence devient un fichier, pas une intention
J’ai passé des années à écrire des articles pour mes blogs sans jamais me poser la question du « système ». Je rédigeais au feeling, et ça marchait à peu près. Puis je suis passé à l’automatisation avec Python et l’API DeepSeek pour mon service Maj’Article IA.
Et là, tout change. Une machine ne devine pas ton ton, tes obsessions, ta façon de couper une phrase. Soit tu lui donnes un cadre, soit elle part dans tous les sens. C’est exactement le problème que le design MD de Google prétend résoudre : transformer une intention vague en fichier exploitable.
La cohérence n’existe pas tant qu’elle n’est pas écrite quelque part. Tout le reste, c’est de la littérature.
Pour aller plus loin
Avertissement : cet article décrit une pratique en évolution rapide. Les formats de fichiers, les noms de tokens et le comportement des agents de codage peuvent changer sans préavis. Vérifiez la documentation officielle de votre outil avant d’appliquer les recommandations ci-dessus à un projet en production.
Article utile ? Dites-le à Google. Ajoutez ce blog à vos sources préférées : un clic, et vous le retrouverez dans vos recherches (et l’AI Mode) au lieu du contenu recyclé par des robots. C’est votre façon de reprendre le contrôle sur ce que vous lisez.
Et si vous avez aimé, partagez (c’est le meilleur coup de pouce pour un blog indépendant qui publie sans algorithme ni sponsor déguisé).
Un clic, gratuit. Nécessite d’être connecté à votre compte Google.
Franchement le coup du fichier DESIGN.md qui se barre en vrille, ça me parle. J'ai passé des heures à corriger l'UI et l'IA me changeait la terminologie ou ajoutait des éléments qui n'existaient pas en prod. Et le pire, je lui ai dit trois fois d'enlever le flou, elle a gardé l'effet quand même. Du coup maintenant je pose des règles strictes pour la stabiliser.