Utiliser un DESIGN.md avec votre agent de code

Un agent de code qui écrit de l'interface sans consigne visuelle choisit des couleurs, des polices et des arrondis au hasard, et le résultat change d'une session à l'autre. Un DESIGN.md règle ce problème : c'est un fichier texte qui décrit l'identité visuelle de votre produit, que l'agent relit avant de produire des écrans.

Ce que contient le fichier

Le format est publié en open source par Google Labs. Un DESIGN.md réunit deux choses : des valeurs exactes en YAML (les « tokens ») et du texte en Markdown qui explique pourquoi ces valeurs existent et comment les appliquer. Les tokens font foi pour les valeurs ; le texte donne le contexte.

Le texte est organisé en sections ##, dans cet ordre. Une section peut être omise si elle ne sert pas votre projet.

Les en-têtes sont en anglais dans la spécification ; gardez-les tels quels, même si le reste du fichier est en français.

Voici le début d'un fichier, avec ses tokens en tête :

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
rounded:
  sm: 4px
  md: 8px
---

Un composant peut reprendre un token par référence plutôt que de répéter la valeur :

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    rounded: "{rounded.sm}"

La spécification précise que la partie composants évolue encore : traitez-la comme une base, pas comme un contrat figé.

Où le placer

Mettez le fichier à la racine du projet, sous le nom DESIGN.md. Pour un projet existant, les ressources du catalogue s'installent dans le projet courant, comme indiqué dans Installer votre première ressource.

Placer le fichier ne suffit pas toujours. Chaque agent charge d'office ses propres fichiers d'instructions, pas les autres :

• Claude Code lit CLAUDE.md (à la racine ou dans .claude/). Il sait aussi lire AGENTS.md quand aucun CLAUDE.md n'existe. Dans un CLAUDE.md, une ligne @DESIGN.md importe le fichier : son contenu est chargé avec les instructions. Les chemins relatifs se résolvent depuis le fichier qui contient l'import, avec quatre niveaux d'imbrication au plus.
• Codex lit AGENTS.md, en partant de la racine du projet jusqu'au dossier de travail.
• Cursor charge les règles de .cursor/rules (fichiers .mdc) et lit aussi AGENTS.md.

Le plus simple est donc de nommer le fichier dans vos instructions :

## Interface
Tout écran respecte DESIGN.md à la racine du projet.
Ne définis aucune couleur, police ou rayon qui n'y figure pas.

Avec Claude Code, remplacez ces deux phrases par @DESIGN.md si vous voulez que le fichier soit toujours chargé. Gardez en tête que le contenu importé occupe de la place dans le contexte à chaque session : un DESIGN.md concis vaut mieux qu'un fichier de dix pages.

Demander à l'agent de s'y conformer

Une fois le fichier en place, dites-le dans la demande plutôt que d'espérer qu'il soit lu :

Lis DESIGN.md. Construis la page de tarifs en utilisant uniquement
ses couleurs, ses polices et ses composants. Signale-moi tout ce qui
manque dans le fichier au lieu de l'inventer.

Trois habitudes aident :

1. Demandez de signaler les manques. Si le fichier ne définit pas de style d'alerte, l'agent doit vous le dire, pas en improviser un.
2. Vérifiez le résultat contre la section Do's and Don'ts. C'est votre liste de contrôle : « une seule action principale par écran », « pas plus de deux graisses ».
3. Relisez le code, pas seulement la capture. Cherchez des valeurs écrites en dur (#3b82f6) qui ne viennent pas du fichier.

Valider et exporter le fichier

L'outil en ligne de commande publié avec la spécification contrôle un DESIGN.md : références de tokens cassées, contrastes WCAG insuffisants, structure incomplète.

npx @google/design.md lint DESIGN.md

Il exporte aussi les tokens vers d'autres formats, par exemple un thème Tailwind v4 en CSS :

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

Cet outil est facultatif : un DESIGN.md reste un simple fichier Markdown que n'importe quel agent peut lire.

L'adapter à votre marque

Le fichier d'un autre ne décrit pas votre marque. Pour le faire vôtre :

1. Remplacez les tokens. Couleurs, polices, rayons, espacements : mettez vos valeurs, en gardant les noms de tokens pour que les références continuent de fonctionner.
2. Réécrivez l'Overview. Une phrase sur le ton et le public vaut plus qu'un long paragraphe : elle guide l'agent quand aucune règle ne couvre le cas.
3. Supprimez ce que vous n'utilisez pas. Une section absente est permise ; une section fausse induit l'agent en erreur.
4. Complétez Do's and Don'ts avec vos erreurs réelles. Chaque fois que l'agent se trompe deux fois de la même manière, ajoutez une ligne.
5. Vérifiez les contrastes. Un lint ou un contrôle manuel, avant de livrer.

DESIGN.md inspirés de marques réelles

Le catalogue propose des fichiers DESIGN.md qui s'inspirent du style visuel de produits connus. Ils servent de point de départ pour voir à quoi ressemble un fichier complet, ou pour obtenir une direction visuelle proche d'un produit que vous aimez.

Ces fichiers ne sont ni affiliés aux marques citées ni approuvés par elles. Les noms et logos restent la propriété de leurs titulaires. Ne livrez pas un site qui imite l'identité d'une autre marque : prenez le fichier comme une inspiration, puis remplacez les tokens par les vôtres. Chaque fiche indique l'auteur, la licence d'origine et le lien vers la source.