Documentation

Qu’est-ce que DESIGN.md ?

DESIGN.md est un fichier texte qui décrit un design system pour les agents IA. Le front matter YAML, en haut, contient les tokens de design exacts : couleurs, typographie, espacements, coins arrondis et composants. Le corps en Markdown, en dessous, explique comment et pourquoi les appliquer. Humains et agents peuvent le lire, le modifier et le faire respecter.

README.md explique ce qu’est un projet. AGENTS.md indique aux agents de code comment le construire. DESIGN.md leur dit à quoi il doit ressembler et quelle impression il doit donner, pour que les écrans générés par un agent partagent une même palette, une même échelle typographique et un même langage de composants au lieu de diverger.

D’où vient DESIGN.md

Google a introduit DESIGN.md avec Google Stitch, son outil de design IA, comme l’équivalent design d’AGENTS.md. Google Labs publie le format sous forme de spécification ouverte dans le dépôt google-labs-code/design.md, sous licence Apache 2.0. La spécification DESIGN.md est étiquetée alpha : attendez-vous à ce que le format évolue en mûrissant.

Le même dépôt fournit un paquet npm, @google/design.md, avec une commande lint qui vérifie la structure, les références de tokens cassées et le contraste WCAG, et une commande diff qui compare deux versions d’un fichier token par token.

Anatomie d’un fichier DESIGN.md

Chaque fichier DESIGN.md comporte deux couches. Le front matter YAML contient des tokens de design lisibles par une machine, comme les valeurs exactes des couleurs, les propriétés des polices, les échelles d’espacement et les références de tokens des composants. Le corps en Markdown fournit l’explication du design, lisible par un humain.

La spécification considère les tokens comme les valeurs normatives et le texte comme le contexte pour les appliquer. Les tokens donnent aux agents des valeurs précises. Le texte leur explique pourquoi ces valeurs existent et comment les utiliser de façon cohérente d’un écran à l’autre.

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

Les huit sections canoniques

Le corps en Markdown utilise des titres ##. Les sections non pertinentes peuvent être omises, mais celles qui sont présentes doivent suivre cet ordre. Un titre présent deux fois rend le fichier invalide ; les sections inconnues sont conservées.

  1. Overview (ou Brand & Style). L’apparence et l’impression générale en quelques phrases : ambiance, densité, personnalité.
  2. Colors. Chaque token de couleur et son rôle, par exemple les actions principales ou les surfaces de page.
  3. Typography. Les familles de polices et l’échelle typographique, des grands titres aux petits libellés.
  4. Layout (ou Layout & Spacing). L’échelle d’espacement, la grille, les largeurs de contenu et les gouttières.
  5. Elevation & Depth (ou Elevation). Comment les surfaces se distinguent : ombres, bordures, teintes.
  6. Shapes. Les rayons d’angle et les autres règles de forme.
  7. Components. Boutons, champs, cartes et autres atomes, avec leurs tokens et leurs états.
  8. Do’s and Don’ts. Les règles qu’un agent ne doit pas enfreindre.

Un corps Markdown compact avec chaque section canonique dans l’ordre. Adaptez le contenu à votre produit, gardez les titres et leur ordre.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Tokens de design et schéma

DESIGN.md intègre les tokens de design sous forme de front matter YAML au début du fichier. Le bloc de front matter commence par une ligne contenant exactement --- et se termine par le même délimiteur.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Les noms d’échelle courants sont xs, sm, md, lg, xl et full, mais toute clé descriptive est valide. Les tokens d’espacement se trouvent dans le YAML sous spacing: et sont décrits dans la section Layout du corps en Markdown.

Types de tokens

Couleur
N’importe quelle chaîne de couleur CSS valide. L’hexadécimal au format #RRGGBB est le choix recommandé par défaut, par exemple "#1A1C1E".
Dimension
Un nombre suivi d’une unité px, em ou rem. Exemples :48px,-0.02em.
Référence de token
Entourée d’accolades et pointant vers une valeur de l’arbre YAML. Exemple :{colors.primary}.
Typographie
Un objet composite contenant des propriétés de police comme la famille, la taille, la graisse, l’interlignage et l’espacement des lettres. Voir Propriétés typographiques.

Propriétés typographiques

fontFamily
Le nom de la famille de polices.
fontSize
La taille de police, sous forme de dimension.
fontWeight
La graisse numérique, par exemple 400 ou 700.
lineHeight
Une dimension ou un multiplicateur sans unité. Les valeurs sans unité sont recommandées.
letterSpacing
L’ajustement de l’espacement des lettres, sous forme de dimension.
fontFeature
Configure font-feature-settings.
fontVariation
Configure font-variation-settings.

Références de tokens

Une référence de token est entourée d’accolades et contient le chemin d’objet vers une autre valeur de l’arbre YAML. Pour la plupart des groupes de tokens, la référence doit pointer vers une valeur primitive plutôt que vers un groupe. Dans la section des composants, les références à des valeurs composites, comme les niveaux typographiques, sont autorisées.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Composants

La section des composants regroupe les consignes de style pour les atomes comme les boutons, les chips, les listes, les champs, les cases à cocher, les boutons radio et les infobulles. Un design system peut définir d’autres composants importants pour son domaine.

Les variantes pour les états survol, actif ou pressé sont définies comme des entrées de composant distinctes, avec des noms de clés apparentés, comme button-primary-hover.

backgroundColor
Couleur
textColor
Couleur
typography
Typographie
rounded
Dimension
padding
Dimension
size
Dimension
height
Dimension
width
Dimension

Noms de tokens recommandés

Ces noms sont des recommandations, pas des obligations. Ils offrent des valeurs par défaut utiles pour la cohérence entre systèmes.

Couleurs : primary, secondary, tertiary, neutral, surface, on-surface, error

Typographie : headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Arrondis : none, sm, md, lg, xl, full

Comment les agents IA utilisent DESIGN.md

Placez DESIGN.md à la racine de votre dépôt, à côté de README.md et d’AGENTS.md. Tout agent ayant accès aux fichiers peut le lire, mais la plupart ne le chargent pas d’eux-mêmes. Faites-y référence dans les instructions que votre agent lit déjà, ou nommez-le dans le prompt quand vous demandez du travail d’interface. Une courte mention suffit :

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.
Claude Code
Lit les fichiers de votre dépôt et charge CLAUDE.md au démarrage. Ajoutez-y une ligne qui renvoie à DESIGN.md, ou mentionnez le fichier dans votre prompt.
Cursor
Ajoutez DESIGN.md au contexte du chat, ou faites-y référence dans une règle de projet pour qu’il s’applique à chaque demande d’interface.
GitHub Copilot
Faites référence à DESIGN.md dans le fichier d’instructions Copilot de votre dépôt, ou joignez-le dans le chat quand vous demandez du travail d’interface.
Google Stitch
Là où le format est né. Stitch utilise un DESIGN.md pour que les écrans générés partagent une même palette, une même échelle typographique et un même langage de composants.

L’agent prend ensuite les valeurs exactes dans les tokens (le hex d’un bouton principal, la taille d’un libellé body-md) et s’appuie sur le texte pour décider où les utiliser.

DESIGN.md, AGENTS.md et README.md

Les trois fichiers cohabitent et répondent à des questions différentes. DESIGN.md ne remplace pas AGENTS.md ; les deux fonctionnent ensemble.

FichierÉcrit pourRépond à
README.mdLes personnes qui utilisent le projet ou y contribuentQu’est-ce que c’est, et comment le lancer ?
AGENTS.mdLes agents de codeComment construire, tester et modifier ce code ?
DESIGN.mdLes agents de code et de designÀ quoi doit ressembler l’interface et quelle impression doit-elle donner ?

De vrais exemples de DESIGN.md

Le moyen le plus rapide de comprendre le format est de lire quelques vrais fichiers. Chacune de ces pages de la galerie montre un DESIGN.md extrait du site public de la marque, avec sa palette et son spécimen typographique. Ce ne sont pas des chartes de marque officielles.

Parcourir tous les exemples de DESIGN.md

Comment obtenir un DESIGN.md

  1. Rédigez-le à la main. Partez de la spécification et des exemples ci-dessus, puis vérifiez le fichier avec le validateur DESIGN.md gratuit ou la commande lint de Google.
  2. Partez d’un exemple. Copiez un fichier de la galerie et modifiez les tokens et le texte pour qu’ils correspondent à votre produit.
  3. Générez-le à partir d’un site en ligne. Collez une URL publique dans Design Extractor. Il affiche le site dans un navigateur et renvoie un DESIGN.md conforme à la spécification ci-dessus, avec ses couleurs, sa typographie, ses espacements et ses composants. La page du générateur de DESIGN.md explique ce que vous obtenez. La même extraction fonctionne depuis l’extension Chrome et depuis votre agent via le serveur MCP.

FAQ

Questions sur DESIGN.md

Des réponses courtes sur le format DESIGN.md, son origine et son utilisation avec les agents IA.

Un DESIGN.md est un fichier texte qui décrit un design system pour les agents IA. Le front matter YAML, en haut, contient les tokens exacts (couleurs, typographie, espacements, coins arrondis et composants), et le corps en Markdown, en dessous, explique comment et pourquoi les appliquer. Les agents lisent les tokens pour les valeurs et le texte pour l’intention.

Google a introduit DESIGN.md avec Stitch, son outil de design IA. Google Labs publie la spécification sur GitHub (google-labs-code/design.md) sous licence Apache 2.0. Le format est étiqueté alpha : attendez-vous à des changements à mesure qu’il mûrit.

AGENTS.md indique aux agents de code comment construire un projet et travailler dessus : commandes, conventions, tests. DESIGN.md leur dit à quoi le produit doit ressembler et quelle impression il doit donner : couleurs, typographie, espacements, formes et composants. README.md s’adresse aux humains qui utilisent le projet ou y contribuent. Beaucoup de dépôts gardent les trois côte à côte.

Placez-le à la racine du dépôt, à côté de README.md et d’AGENTS.md, pour que les agents ayant accès aux fichiers le trouvent. Faites-y ensuite référence dans les instructions que votre agent charge déjà, comme AGENTS.md, CLAUDE.md, une règle Cursor ou vos instructions Copilot, ou mentionnez-le dans le prompt quand vous demandez du travail d’interface.

Non. La spécification permet d’omettre les sections qui ne s’appliquent pas, mais celles que vous gardez doivent suivre l’ordre canonique : Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts. Un titre de section ne doit pas apparaître deux fois, et les sections inconnues sont conservées plutôt que rejetées.

Le paquet npm de Google, @google/design.md, dispose d’une commande lint qui vérifie la structure, les références de tokens cassées et le contraste WCAG. Design Extractor propose aussi un validateur DESIGN.md gratuit qui vérifie la structure et les tokens dans votre navigateur et prévisualise le fichier, sans l’envoyer.

Rédigez-le à la main à partir de la spécification, copiez-en un depuis une galerie de vrais exemples comme point de départ, ou générez-le à partir du site en ligne. Design Extractor prend une URL publique, affiche le site dans un navigateur et renvoie un DESIGN.md avec ses couleurs, sa typographie, ses espacements et ses composants, prêt à déposer dans votre dépôt.

Vous en voulez un pour un site que vous aimez ?

Collez une URL publique et obtenez son DESIGN.md.

Extraire un site