DESIGN.md : le fichier qui transforme vos agents IA en designers

Vous demandez à Claude Code ou Cursor de construire une landing page. Le résultat fonctionne, mais ressemble à un template Bootstrap générique. Les couleurs sont aléatoires, la typographie incohérente, les espacements approximatifs. Le problème ne vient pas du modèle — il lui manque le contexte design.

DESIGN.md résout exactement ce problème. Introduit par Google Stitch et popularisé par le projet open source awesome-design-md (plus de 10 000 étoiles sur GitHub en quelques jours), ce simple fichier Markdown encode votre design system entier dans un format que les LLM comprennent nativement.

Le problème : des agents qui codent bien mais designent mal

Les agents IA de codage ont fait des progrès spectaculaires. Ils génèrent du code fonctionnel, gèrent les dépendances, écrivent des tests. Mais côté visuel, ils improvisent.

Sans contexte design explicite, un agent va :

Choisir des couleurs arbitraires ou tomber dans le bleu/gris par défaut
Utiliser des tailles de police sans hiérarchie cohérente
Appliquer des espacements inconsistants entre les composants
Produire des interfaces qui fonctionnent mais ne ressemblent à rien de professionnel

Les exports Figma, fichiers JSON de design tokens ou systèmes comme Style Dictionary existent déjà. Mais ils sont conçus pour des pipelines outillés, pas pour des LLM. Un fichier JSON de 2 000 lignes de tokens ne donne pas à un agent le contexte pour prendre de bonnes décisions design.

DESIGN.md : le README de votre design system

Le concept est simple : un fichier Markdown placé à la racine de votre projet, que tout agent IA peut lire et interpréter. Comme CLAUDE.md définit les règles de comportement pour Claude Code, DESIGN.md définit les règles visuelles.

Un DESIGN.md typique contient neuf sections standardisées :

Thème visuel et atmosphère — la direction artistique générale
Palette de couleurs et rôles — primaire, secondaire, accent, sémantique
Règles typographiques — familles, échelle, graisses, hauteurs de ligne
Styles des composants — boutons, cartes, formulaires, navigation
Principes de layout — grille, conteneurs, breakpoints
Profondeur et élévation — ombres, superposition, z-index
Ce qui est permis et interdit — les garde-fous du design
Comportement responsive — adaptations mobile, tablette, desktop
Guide de prompt pour agents — instructions spécifiques pour les IA

Exemple minimal

Voici à quoi ressemble un DESIGN.md simplifié :

## Couleurs
- Primaire : #1A73E8
- Primaire foncé : #1557B0
- Surface : #FFFFFF
- Texte principal : #1F2937
- Texte secondaire : #6B7280
- Succès : #10B981
- Erreur : #EF4444
 
## Typographie
- Famille : Inter, sans-serif
- H1 : 32px, graisse 700
- H2 : 24px, graisse 600
- Corps : 16px, graisse 400
- Caption : 14px, graisse 400
 
## Espacement
- Unité de base : 8px
- Valeurs : 4, 8, 16, 24, 32, 48px
 
## Composants
- Border-radius bouton : 8px
- Ombre carte : 0 1px 3px rgba(0,0,0,0.12)
- Padding conteneur : 24px

Quand un agent lit ce fichier, il ne fait plus de suppositions. Il applique vos valeurs exactes.

Le projet awesome-design-md

Le dépôt VoltAgent/awesome-design-md a catalysé cette tendance. Il propose 55 fichiers DESIGN.md extraits de sites web réels, couvrant un large éventail de styles :

IA et Machine Learning : Claude, Cohere, ElevenLabs, Mistral AI, Ollama, Replicate, xAI

Outils développeurs : Cursor, Linear, Vercel, Supabase, Sentry, PostHog, Raycast

Design et productivité : Figma, Notion, Framer, Miro, Airtable, Webflow

Fintech : Stripe, Coinbase, Revolut, Wise

Entreprise et consumer : Apple, Airbnb, Spotify, Uber, BMW, NVIDIA, SpaceX

Chaque dossier contient le DESIGN.md plus des fichiers preview.html et preview-dark.html pour visualiser le résultat.

Utilisation concrète

# Cloner le dépôt
git clone https://github.com/VoltAgent/awesome-design-md.git
 
# Copier un design system dans votre projet
cp awesome-design-md/designs/stripe/DESIGN.md ./DESIGN.md
 
# Votre agent IA le détecte automatiquement

Ensuite, demandez simplement à votre agent :

« Construis une page pricing en suivant le DESIGN.md du projet. »

Le résultat respectera les couleurs, la typographie, les espacements et les composants de Stripe — sans export Figma ni configuration supplémentaire.

Pourquoi Markdown et pas JSON ou YAML

Le choix du Markdown est délibéré. Les LLM traitent le Markdown comme un format natif — ils en génèrent constamment et le comprennent intuitivement. Un fichier JSON de tokens est techniquement précis mais manque de contexte sémantique.

Comparons :

JSON (technique, pas de contexte) :

"button.borderRadius": "8px",
"button.primary.bg": "#1A73E8"

Markdown (sémantique, contextuel) :

## Boutons
- Border-radius : 8px pour un aspect moderne mais accessible
- Fond primaire : #1A73E8 — utilisé pour les actions principales
- Ne jamais utiliser de coins carrés (radius 0)

Le Markdown permet de mélanger les valeurs avec des intentions et des contraintes. La section "Ce qui est permis et interdit" est particulièrement puissante : elle agit comme des garde-fous que les agents IA respectent.

Compatibilité avec les outils

DESIGN.md fonctionne avec tout agent qui lit les fichiers du projet :

Claude Code — lit automatiquement les fichiers Markdown à la racine
Cursor — intègre le contexte des fichiers du projet dans les prompts
GitHub Copilot Workspace — utilise le contexte du repository
Google Stitch — conçu nativement pour DESIGN.md
Gemini CLI — lit les fichiers du répertoire de travail
Agents personnalisés (LangChain, CrewAI) — ajoutez le fichier comme contexte

Créer votre propre DESIGN.md

Vous pouvez partir de zéro ou adapter un fichier existant. Voici les étapes recommandées :

1. Extraire les tokens existants

Si vous avez un design system dans Figma, Tailwind ou un autre outil, documentez les valeurs clés : couleurs, polices, espacements, rayons de bordure, ombres.

2. Ajouter le contexte sémantique

Ne listez pas simplement des valeurs hexadécimales. Expliquez les rôles :

## Couleurs
- Primaire (#2563EB) : actions principales, liens, focus
- Destructif (#DC2626) : suppression, erreurs critiques
- Surface (#F9FAFB) : fond des cartes et modales

3. Inclure les contraintes

La section la plus sous-estimée. Les agents IA respectent les interdictions explicites :

## Règles strictes
- Ne jamais utiliser plus de 3 couleurs sur un même écran
- Toujours maintenir un ratio de contraste WCAG AA minimum
- Les boutons primaires ont toujours un padding horizontal de 24px minimum
- Ne jamais centrer des paragraphes de texte longs

4. Versionner avec le code

Placez DESIGN.md à la racine du projet, dans le même repository que le code. Les modifications de design passent par des pull requests, avec revue et historique.

Un pattern qui converge

DESIGN.md fait partie de la tendance des "fichiers de connaissances pour agents". Le stack émergeant ressemble à :

CLAUDE.md / .cursorrules — règles de comportement et conventions de code
DESIGN.md — système de design et règles visuelles
SPEC.md — spécifications produit et exigences fonctionnelles
AGENTS.md — configuration des workflows multi-agents

Chaque fichier encode des connaissances institutionnelles dans un format que les agents IA peuvent naviguer. Le développement logiciel se restructure autour de documents Markdown structurés qui servent de contrat entre humains et agents.

Limites actuelles

DESIGN.md est puissant mais pas parfait :

Pas de gestion des états complexes — les variants, les animations et les micro-interactions restent difficiles à encoder en Markdown
Risque de dérive — si le fichier diverge du design system réel dans Figma, les agents produiront des résultats incorrects
Pas de validation automatique — rien ne vérifie que le code généré respecte effectivement le DESIGN.md
Taille limitée — un design system complet d'entreprise peut dépasser la fenêtre de contexte utile

Pour les systèmes complexes avec des centaines de composants, DESIGN.md complète Figma plutôt que de le remplacer. Il excelle pour donner une direction cohérente aux agents, pas pour encoder chaque pixel.

Commencer maintenant

La barrière à l'entrée est presque nulle :

Copiez un DESIGN.md depuis awesome-design-md qui se rapproche de votre identité visuelle
Adaptez les valeurs à votre charte graphique (couleurs, polices, espacements)
Testez avec un prompt : demandez à votre agent de construire un composant et comparez le résultat
Itérez : ajoutez des contraintes quand vous remarquez des incohérences

En cinq minutes, vos agents IA passent de "développeur frontend junior qui improvise" à "développeur qui suit une maquette précise". Le tout avec un simple fichier texte.