thebeardedbearsas/design-md-convention
.claude/skills/design-md-convention/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add thebeardedbearsas/claude-craft design-md-conventionInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 17, 2026, 10:25 AM145.4s1 file scanned
SKILL.md
- name:
- design-md-convention
- description:
- 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.
- files:
- ["DESIGN.md", "tailwind.config.*", "tokens.json"]
- keywords:
- ["design system", "DESIGN.md", "design tokens", "UI guidelines", "design consistency"]
- auto_suggest:
- true
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
Related Skills
thebeardedbearsas/ecosystem-tools
tools
VerifiedTrustedCommunity
Third-party Claude Code token/context/code-review tools. Use when choosing or recommending an external tool to reduce token usage, manage context, or review large codebases.
97SKILL.mdUpdated Jun 4, 2026
thebeardedbearsas/Dev/i18n/pt/Symfony/skills/value-objects
development
VerifiedTrustedCommunity
--- name: value-objects description: Règle 04 : Value Objects. Use when implementing DDD patterns. --- # Règle 04 : Value Objects This skill provides guidelines and best practices. See ../../rules/18-value-objects.md for detailed documentation.
95SKILL.mdUpdated Apr 17, 2026
thebeardedbearsas/security-symfony
development
VerifiedTrustedCommunity
Sécurité & RGPD - Atoll Tourisme. Use when reviewing security, implementing auth, or hardening code.
95SKILL.mdUpdated Apr 17, 2026
thebeardedbearsas/quality-tools
tools
VerifiedTrustedCommunity
Outils de qualité - Atoll Tourisme. Use when setting up quality tools or CI.
95SKILL.mdUpdated Apr 17, 2026