design-md-convention
Skill108 starsChanged 7 days agoMITView on GitHub
Convention DESIGN.md pour design systems AI-friendly. Use when setting up a new project UI, documenting design tokens, or generating UI consistent with a design system.
In this repository61 other files it gives its agents.
- docs/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- .claude/references/angular/CLAUDE.mdCLAUDE.md
- .claude/references/flutter/CLAUDE.mdCLAUDE.md
- .claude/references/laravel/CLAUDE.mdCLAUDE.md
- .claude/references/paperclip/CLAUDE.mdCLAUDE.md
- .claude/references/reactnative/CLAUDE.mdCLAUDE.md
- .claude/references/svelte/CLAUDE.mdCLAUDE.md
- .claude/references/symfony/CLAUDE.mdCLAUDE.md
- .claude/references/vite/CLAUDE.mdCLAUDE.md
- .claude/references/vuejs/CLAUDE.mdCLAUDE.md
- aggregatesSkill
- api-gatewaySkill
- architectSkill
- architecture-clean-dddSkill
- architectureSkill
- asyncSkill
- atomic-tasksSkill
- coding-standardsSkill
- cqrsSkill
- ddd-patternsSkill
- debug-methodicalSkill
- docker-hadolintSkill
- doctrine-extensionsSkill
- documentationSkill
- domain-eventsSkill
- dynamic-workflowsSkill
- ecosystem-toolsSkill
- edge-computingSkill
- event-drivenSkill
- git-workflowSkill
- graphqlSkill
- i18nSkill
- kiss-dry-yagniSkill
- monorepoSkill
- multitenantSkill
- navigationSkill
- observabilitySkill
- parallel-worktreesSkill
- performanceSkill
- quality-toolsSkill
- remotionSkill
- security-flutterSkill
- security-reactnativeSkill
- security-reactSkill
- securitySkill
- security-symfonySkill
- socratic-brainstormSkill
- solid-principlesSkill
- state-managementSkill
- sub-agents-patternsSkill
- testing-flutterSkill
- testing-pythonSkill
- testing-reactnativeSkill
- testing-reactSkill
- testingSkill
- testing-symfonySkill
- toolingSkill
- value-objectsSkill
- wasmSkill
- The first 60 shown.
The file
Files
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 palette4. 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 systemGé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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

