Comment générer un DESIGN.md (et à quoi cela sert)

Un DESIGN.md se place à côté du code et décrit le design prévu dans des termes exploitables par un agent. Les agents de code implémentent bien les interfaces, mais sans direction artistique, ils ont tendance à revenir à un style neutre par défaut. Ce nom est devenu depuis un petit écosystème : Google Labs a open-sourcé une spécification de format DESIGN.md (provenant de l'équipe Stitch, Apache 2.0, toujours en version alpha), laquelle a récolté des dizaines de milliers d'étoiles sur GitHub en quelques mois. Leur spécification associe des tokens lisibles par machine dans un front matter YAML à un raisonnement lisible par l'humain en prose, et fournit un CLI qui valide les fichiers et exporte vers Tailwind et le format design-token du W3C.

Cette structure, alliant valeurs exactes et intention écrite dans un seul fichier, est la même conclusion que celle défendue par ce guide. Il est important d'être précis sur ce que la spécification apporte et ce qu'elle n'apporte pas. Un format vous indique où placer les tokens et la prose. Il ne produit pas le design system lui-même : les tokens doivent provenir de quelque part, et les motifs, les interdictions et les règles de structure de page doivent toujours être décidés par quelqu'un. Les sites de catalogues collectent des fichiers DESIGN.md finis ; les approches de génération présentées ci-dessous en produisent un à partir d'un système réel, ce qui fait la différence entre un fichier qui est simplement valide et un fichier qui modifie ce qu'un agent construit.

Un DESIGN.md a besoin de plus qu'une simple liste de couleurs. Les agents ont également besoin de directives sur la mise en page, l'espacement, le traitement des composants et les détails qui distinguent un design d'un autre. Un brief utile consacre la majeure partie de son texte à ces décisions.

Un brief complet couvre l'ensemble du système, pas seulement les tokens. Le DESIGN.md généré par Identity Forge est organisé selon les sections suivantes :

• Overview : ce qu'est le design, à qui il s'adresse et le sentiment recherché, en une phrase ou deux.
• Colors : les tokens sémantiques sous forme de variables CSS prêtes à être collées dans globals.css, en modes clair et sombre. Explication des tokens de couleur sémantiques.
• Typography : l'association typographique, l'échelle, l'approche (tracking) et les graisses, ainsi qu'une configuration de police prête pour Next.js.
• Layout : la base d'espacement, la largeur du conteneur et les règles de composition.
• Elevation & Depth : le système d'ombres (ou l'absence délibérée de celui-ci).
• Shapes : les rayons de courbure par élément (boutons, cartes, champs de saisie, badges) et le traitement des bordures.
• Components : la manière dont les composants principaux doivent être traités, avec un exemple.
• Page Structure & Layout : comment composer des pages entières ; c'est ici que l'on empêche les résultats d'IA génériques.
• Personality & References : la voix et les références qui sous-tendent le design.
• Distinctive Motifs : les éléments signatures à reproduire ; "ils définissent le design autant que les tokens."
• Do's & Don'ts : les règles qui maintiennent l'interface générée dans l'univers du design.
• Agent Rules : des instructions explicites destinées à l'agent de code lui-même.

La liste ci-dessus détaille ce que couvre un brief complet. Il est utile de savoir à quel point les fichiers publiés en sont éloignés, car l'écart est constant et vous indique précisément quelles sections prioriser si vous en rédigez un manuellement.

Nous avons analysé 299 fichiers DESIGN.md publiés dans des dépôts et répertoires publics : des fichiers réels, écrits pour guider les agents sur le plan du design. 72 étaient spécifiquement dédiés au design visuel.

Comparez les deux dernières lignes et le schéma est sans équivoque. La typographie est mentionnée dans 83 % des fichiers, alors que 44 % des fichiers n'indiquent jamais une seule taille. Ce sont des documents qui parlent de typographie sans jamais préciser la dimension des éléments.

Le chiffre concernant les adjectifs explique le reste. « Clean » apparaît dans 39 % de ces fichiers et « modern » dans 36 %. Ce sont deux mots auxquels un modèle répond en produisant le centre de sa distribution d'entraînement, ce qui correspond précisément au résultat générique que le fichier était censé éviter.

L'unique distinction entre un brief qui modifie le résultat et un autre qui ne le fait pas : une phrase peut-elle être vérifiée par rapport à un écran rendu ? Si ce n'est pas le cas, c'est de la décoration.

Chaque entrée de la colonne de droite peut être vérifiée en consultant un écran ou en effectuant un grep dans le code. Chaque entrée de la colonne de gauche peut être satisfaite par presque n'importe quoi, ce qui signifie qu'elle n'impose aucune contrainte.

Trois propriétés distinguent une interdiction appliquée d'une interdiction ignorée.

La troisième ligne est celle que l'on oublie le plus souvent. Une interdiction sans alternative ouvre une brèche que le modèle comble en puisant dans la même distribution d'entraînement que celle que vous essayiez d'éviter. Chaque "jamais X" nécessite un "à la place, Y".

Si vous en rédigez un à la main plutôt que de le générer, voici une structure de départ viable. Elle est volontairement courte. Un brief que personne ne peut garder en tête entre en concurrence avec la tâche réelle pour l'attention du modèle. Environ 400 lignes constituent un plafond gérable ; ce squelette est bien en dessous.

# DESIGN.md

## Overview

A dense internal tool for operations staff who work in it for hours.
Quiet, information-first. Nothing here has to convince anyone of anything.

## Don'ts

- No gradients
- No drop shadows — elevation is a surface step plus a 1px border
- No font-weight above 600
- No colour value outside the tokens in globals.css
- No border-radius above 12px
- No decorative use of the state colours

## Colours

Defined as semantic roles in globals.css, light and dark.
Do not restate values here — read them from that file.

- `--primary` — primary buttons and active nav state ONLY.
  Never on text, borders, backgrounds or gradients.
- `--muted-foreground` — secondary and supporting text only.
- `--border` — structural edges and dividers.
- `--destructive` / `--success` / `--warning` — reserved for state.

## Typography

Family: Inter (variable). Weights 400 and 600 only.
Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48.
Tracking: -0.02em at 32px and above, 0 below, +0.02em on 12px caps.
Hierarchy comes from size and colour, never from weight above 600.

## Spacing & density

Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. No other values.
Controls: 8–12px padding. Table rows: 32px. Section gap: 32px.

## Elevation

A surface step plus a 1px `--border`. Never a box-shadow.

## Shapes

Controls 6px. Cards and panels 12px. Nothing above 12px.

## Composition

One primary action per section.
Related controls share a group; unrelated ones are separated by a full step.
Tables are never nested inside cards.

## Motifs

Section headings carry a 2px `--primary` rule on the left edge.
Numeric columns are always tabular-nums and right-aligned.
Empty states are a single line of `--muted-foreground` text, never an illustration.

## Agent rules

Read this file before writing or editing any UI.
Match the nearest existing component in this repo rather than inventing a
new pattern. If no similar component exists, say so before writing one.

Deux éléments de ce fichier valent la peine d'être copiés, même si vous changez tout le reste. Les interdictions arrivent en second lieu, avant tout élément qu'elles pourraient modifier, afin qu'un modèle lisant de haut en bas rencontre les contraintes avant les permissions. De plus, la section des couleurs renvoie vers globals.css plutôt que de répéter les valeurs : dès qu'une valeur hexadécimale existe à deux endroits, l'un sera mis à jour et l'autre non, et le modèle utilisera avec assurance la version obsolète.

Un DESIGN.md ne vaut que par le système qui le soutient. Voici le kit gratuit ambient-sage : les tokens, polices et traitements décrits dans son DESIGN.md, rendus en direct :

1. 1

   CLI : écrire le DESIGN.md + les tokens dans votre repo

   La voie la plus rapide. Choisissez un slug de kit dans la galerie et appliquez-le ; vous obtenez un DESIGN.md commité ainsi qu'un fichier de tokens correspondant.

   Copy

   identityforge apply ambient-sage

2. 2

   MCP : laisser l'agent le récupérer

   Une fois le serveur MCP installé, l'agent appelle get_design_md(slug) pour lire le brief complet et apply_theme pour l'écrire. Installez-le pour votre outil :

   Copy

   npx --yes identityforge@latest install --client claude-code

3. 3

   shadcn : installer les tokens référencés par le DESIGN.md

   Si vous ne voulez que les valeurs, l'élément du registre installe directement les variables CSS du kit.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

Identity Forge génère le DESIGN.md et les tokens à partir du même kit, donc le texte décrit les valeurs de la feuille de style. Pour comprendre en quoi cela diffère de l'adaptation manuelle d'une entrée de catalogue DESIGN.md, consultez Identity Forge vs getdesign.md.

Écrire le fichier et supposer qu'il a été pris en compte est le meilleur moyen pour les équipes de découvrir le problème trois semaines plus tard. Quatre vérifications, de la plus simple à la plus complexe.

1. 1

   Grep pour les valeurs de couleurs littérales

   Si l'agent respecte les rôles sémantiques, aucune valeur hexadécimale ne doit se trouver en dehors du fichier de tokens. C'est le signal le plus rapide possible.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Utilisez grep pour rechercher les graisses de police interdites

   La graisse est l'endroit où la hiérarchie revient discrètement aux valeurs par défaut ; c'est le premier signe qu'une consigne d'interdiction n'est pas appliquée.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Demandez le même écran deux fois, dans des sessions distinctes

   La cohérence entre les sessions est le véritable test. Si deux exécutions diffèrent significativement sur l'espacement, le rayon des bordures ou la hiérarchie, le diff vous indique précisément quelle section du brief est manquante.

4. 4

   Construisez d'abord un écran en mode sombre

   Si le mode sombre a été déduit plutôt que défini, c'est ici qu'il apparaît : ombres inertes, gris moyens ternes, accent trop criard. Il est bien moins coûteux de s'en rendre compte sur le premier écran que sur le vingtième.

Les deux premiers doivent être intégrés à la CI. Un contrôle qui rejette une pull request contenant une valeur hexadécimale brute fait plus pour la cohérence à long terme que n'importe quelle quantité de texte, ce qui est la même conclusion que celle atteinte par Salesforce avec le linter SLDS.