design-md-convention

DESIGN.md — Convention Design System AI-Friendly

Convention inspirée de VoltAgent/awesome-design-md (55+ design systems populaires, concept Google Stitch).

Principe : un fichier DESIGN.md en markdown à la racine du projet sert de source de vérité pour les agents IA qui génèrent ou modifient l'UI. Pas de Figma, pas de JSON complexe, juste du texte lisible par humain et par LLM.

Pourquoi DESIGN.md ?

Problème sans DESIGN.md	Solution avec DESIGN.md
IA génère des couleurs aléatoires	IA lit la palette définie
Incohérence spacing entre composants	IA applique l'échelle documentée
Typographie variable	IA utilise les tokens définis
Onboarding designer/dev lent	DESIGN.md = réponse unique
Dépendance à Figma pour chaque décision	Markdown versionné avec le code

Structure recommandée

Un DESIGN.md contient 7 sections obligatoires :

1. Principes visuels — ton, personnalité, do/don't
2. Design tokens — couleurs, typographie, espacements, rayons, ombres
3. Grille & layout — breakpoints, colonnes, gutters, container widths
4. Composants — liste + variantes + règles d'usage
5. Patterns d'interaction — hover, focus, active, disabled, loading
6. Accessibilité — niveau cible (AA/AAA), contrastes, focus rings
7. Références — lien vers Figma (optionnel), design system inspiré

Voir .claude/templates/DESIGN.md.template pour la structure complète.

Règles de rédaction

1. Concis et structuré

• Tableaux > prose
• Tokens > valeurs hardcoded
• Exemples concrets > théorie

2. Tokens nommés, pas valeurs brutes

❌ MAUVAIS
Primary button: background #3B82F6

✅ BON
| Token | Valeur | Usage |
|-------|--------|-------|
| `color.primary.500` | #3B82F6 | Boutons primaires, liens actifs |
| `color.primary.600` | #2563EB | Hover des éléments primaires |

3. Do / Don't explicites

### Boutons

**DO**
- Utiliser `button.primary` pour l'action principale d'un écran (1 max)
- Utiliser `button.secondary` pour actions secondaires

**DON'T**
- Jamais 2 boutons primaires sur le même écran
- Jamais de couleur custom hors palette

4. Versionner avec le code

DESIGN.md est dans le repo, reviewé en PR au même titre que le code.

Intégration avec agents Claude Craft

Les agents suivants lisent DESIGN.md par défaut :

• @ui-designer — génère UI conforme aux tokens
• @ux-ergonome — valide les patterns d'interaction
• @accessibility-expert — vérifie contrastes vs niveau cible
• @{react,vue,angular}-reviewer — flag les valeurs hardcoded

Workflow recommandé

1. Nouveau projet → copier .claude/templates/DESIGN.md.template à la racine
2. Remplir les 7 sections (30-60 min)
3. Commiter DESIGN.md
4. Référencer depuis @.claude/CLAUDE.md projet : "@DESIGN.md"
5. Les agents IA le chargent automatiquement
6. Mettre à jour à chaque évolution du design system

Génération assistée

Command dédiée (Phase 4) : /uiux:generate-design-md

• Analyse tailwind.config.js ou tokens existants
• Pré-remplit les sections
• Demande validation sur les zones ambiguës

Exemples de DESIGN.md inspirants

• Stripe Dashboard
• Linear
• Vercel
• Liste complète : awesome-design-md

Anti-patterns

Anti-pattern	Solution
DESIGN.md > 500 lignes	Extraire sous-fichiers docs/design/*.md
Prose sans tableaux	Reformater en tokens structurés
Pas de do/don't	Ajouter règles explicites
Screenshots uniquement	Compléter par description textuelle (LLM ne voit pas toujours les images)
Désynchro avec code	Ajouter check CI (lint tokens)

---

Date de dernière mise à jour : 2026-04-15 Version : 1.0.0