TheBeardedBearSAS 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 :
- Principes visuels — ton, personnalité, do/don't
- Design tokens — couleurs, typographie, espacements, rayons, ombres
- Grille & layout — breakpoints, colonnes, gutters, container widths
- Composants — liste + variantes + règles d'usage
- Patterns d'interaction — hover, focus, active, disabled, loading
- Accessibilité — niveau cible (AA/AAA), contrastes, focus rings
- 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.jsou 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