Extraire un Design System du Code Frontend

Analysez le code source d'un frontend pour extraire un document de design system complet (DESIGN.md) qui capture le langage visuel du projet — couleurs, typographie, espacement, motifs de composants et principes de mise en page — directement à partir des fichiers sources, sans avoir besoin de compiler ou afficher l'application.

Pourquoi cela existe

La skill design-md fonctionne à partir du HTML rendu. Mais souvent vous disposez d'une base de code et vous voulez comprendre son design system avant même de pouvoir lancer l'app — peut-être que les dépendances manquent, la build est cassée, ou vous voulez juste un audit rapide. Cette skill lit les fichiers sources eux-mêmes : feuilles de style, fichiers de composants, configurations de thème, et setups Tailwind. C'est plus rapide et ça fonctionne partout.

Quand l'utiliser

• L'utilisateur dispose d'une base de code frontend et veut extraire ou documenter son design system
• L'utilisateur veut migrer l'identité visuelle d'un projet dans Stitch
• L'utilisateur demande d'« auditer le styling » ou de « comprendre le langage de design » d'un repo
• L'utilisateur veut créer un DESIGN.md à partir du code source existant
• L'app ne peut pas être compilée/affichée mais la source est disponible
• L'utilisateur veut unifier ou réconcilier des styles incohérents dans une base de code

Prérequis

• Accès au répertoire source du projet frontend
• Aucune dépendance de build ou runtime nécessaire — cette skill lit uniquement les fichiers source

Flux de travail

Phase 1 : Découverte du Projet

Commencez par comprendre avec quoi vous travaillez. Cela détermine les patterns d'extraction à utiliser.

1. Détecter le Framework et la Stack

Scannez la racine du projet pour les fichiers révélateurs :

Lisez d'abord package.json — il révèle le framework, les outils CSS, et toute bibliothèque de design-tokens (p. ex., style-dictionary, @chakra-ui/react, @mui/material, ant-design). Ce contexte vous dit où chercher les informations de styling.

2. Cartographier l'Arborescence Source

Identifiez les répertoires et fichiers clés que vous analyserez :

src/
├── components/     ← Styles au niveau des composants
├── styles/         ← Feuilles de style globales
├── theme/          ← Définitions de thème, tokens
├── assets/         ← Polices, images
├── app.css         ← Styles racines
└── index.css       ← CSS d'entrée

Vérifiez aussi :

• tailwind.config.js / tailwind.config.ts — Couleurs personnalisées, polices, espacement
• globals.css / global.css — Propriétés personnalisées CSS (variables)
• Tous les fichiers theme.* ou tokens.*
• Configuration de bibliothèque de composants (p. ex., chakra-theme.ts, vuetify.config.ts)

3. Lire les Directives Spécifiques au Framework

Consultez la référence appropriée pour les patterns d'extraction :

• React / Next.js / Tailwind → references/react-tailwind.md
• Vue / Nuxt → references/vue.md
• Svelte / SvelteKit → references/svelte.md
• Angular → references/angular.md
• Plain CSS / SASS / Less → references/plain-css.md

Ces références contiennent des patterns spécifiques au framework pour localiser les couleurs, la typographie, l'espacement et les styles de composants. Lisez celle qui correspond avant de continuer.

Phase 2 : Extraction Approfondie

Travaillez à travers chaque dimension de design systématiquement. Pour chacune, collectez les données brutes à partir des fichiers source, puis synthétisez-les en langage descriptif.

L'objectif n'est pas de dumper chaque propriété CSS — c'est de comprendre l'intention derrière les choix de styling et les décrire en langage humain, éditorial qu'un autre designer (ou Stitch) peut utiliser pour recréer la même ambiance visuelle.

1. Thème Visuel et Atmosphère

Lisez d'abord le styling le plus large pour comprendre l'atmosphère générale :

• Arrière-plan racine : Quel est l'arrière-plan de l'élément body ou racine ? Une crème clair (#f-range) signale aéré/propre ; une #0-#2 sombre signale sombre/dramatique.
• Philosophie d'espacement : Les valeurs d'espacement sont-elles généreuses (32px+) ou serrées ? Vérifiez les valeurs de padding/margin sur les conteneurs racines, les wrappers de section et les composants de carte.
• Densité : Comptez les composants par page/section. Peu avec de l'espace = minimal ; beaucoup serrés = dense en informations.
• Température de couleur : Les neutres sont-ils chauds (crèmes, tans) ou froids (gris-bleu, ardoise) ?
• Ambiance générale : Synthétisez en 1-2 phrases riches qui capturent l'ambiance.

Cherchez ces signaux dans la source :

2. Palette de Couleurs et Rôles

Extraire chaque couleur unique du code et assigner des rôles fonctionnels. Cherchez à travers toutes les couches :

Où trouver les couleurs :

Comment organiser : Groupez les couleurs par fonction, non par teinte :

1. Foundation Primaire — Couleurs d'arrière-plan et de surface
2. Accent et Interactif — Boutons CTA, états actifs, liens
3. Typographie et Hiérarchie de Texte — Texte primaire, secondaire, tertiaire
4. États Fonctionnels — Succès, erreur, avertissement, info

Pour chaque couleur, créez un nom descriptif qui évoque le caractère de la couleur plutôt que sa valeur hex brute :

• ❌ #294056 → "Bleu"
• ✅ #294056 → "Bleu-Sarcelle Muet Profond" — CTA primaire, navigation active

La dédoublonnisation compte. Les bases de code ont souvent des couleurs quasi-dupliquées (p. ex., #333 et #2C2C2C). Consolidez-les sous un nom qui représente le mieux la couleur prévue.

3. Règles Typographiques

Extraire le système typographique complet :

Familles de polices :

• Vérifiez le CSS font-family, Tailwind fontFamily, les liens Google Fonts, ou les déclarations locales @font-face.
• Notez le caractère de chaque police : géométrique vs humaniste, serif vs sans, le feeling qu'elle évoque.

Échelle de type (hiérarchie) :

• Trouvez chaque niveau de heading (H1-H6) et texte de corps, en notant :
  • font-size (en rem ou px)
  • font-weight (valeur numérique + nom descriptif)
  • letter-spacing (et pourquoi — élégance ? compacité ?)
  • line-height (généreux pour la lisibilité ? serré pour l'affichage ?)
• Cartographiez l'utilisation de composants : Quel niveau de heading les cartes de produit utilisent-elles ? Et les sections héros ?

Principes d'espacement :

• Comment l'espacement de texte se rapporte-t-il à l'échelle d'espacement globale ?
• Patterns de letter-spacing sur les headings vs body
• Philosophie de line-height (généreux/relaxe pour le body, serré pour l'affichage)

4. Stylings de Composants

Analysez les 4-5 primitives UI les plus importantes :

Boutons :

• Rayon de coin (et ce qu'il communique — ludique ? professionnel ? minimal ?)
• Schéma de couleur pour les variantes primaire, secondaire et ghost
• États hover/focus/active et timing de transition
• Ratios de padding (horizontal vs vertical)

Cartes / Conteneurs :

• Rayon de coin (souvent différent des boutons — légèrement plus rond)
• Stratégie d'ombre : plate, ombres subtiles au survol, ou toujours élevée ?
• Traitement de bordure : bordures hairline, accents colorés, ou aucune ?
• Padding interne (généreux ou compact ?)
• Traitement d'image dans les cartes (full-bleed, padded, arrondie ?)

Navigation :

• Pattern de layout (barre horizontale, sidebar verticale, drawer)
• Traitement typographique (majuscules, letter-spacing, poids)
• Indicateurs d'état actif/survol (soulignement, couleur, arrière-plan)
• Comportement mobile (hamburger, nav inférieur, drawer)

Inputs et Formulaires :

• Style de bordure et comportement d'état focus
• Cohérence de style de coin avec les boutons
• Sizing de padding et touch-target

Composants Spécifiques au Domaine :

• Identifiez 1-2 composants uniques à ce projet (p. ex., cartes de produit, widgets de dashboard, bulles de chat) et décrivez leurs patterns de styling.

5. Principes de Layout

Extraire le système structurel :

Grille et Structure :

• Largeur max du contenu (à partir de max-width sur les conteneurs)
• Système de colonnes (patterns CSS Grid, Flexbox, breakpoints définis)
• Breakpoints responsifs (à partir des media queries ou config Tailwind)

Stratégie d'Espacement Blanc :

• Unité d'espacement de base (grille 8px ? 4px ? personnalisée ?)
• Marges de section (combien d'espace entre les sections majeures)
• Padding de bord (marges de page à différents breakpoints)

Alignement et Équilibre Visuel :

• Patterns d'alignement de texte (héros centrés, body aligné à gauche)
• Ratios image-texte
• Distribution du poids visuel

Comportement Responsif :

• Mobile-first ou desktop-first ?
• Comment les grilles s'effondrent ? Échelle de padding ?
• Sizing de touch-target

6. Notes de Génération Stitch

Synthétisez l'extraction en prompts actionnables pour Stitch :

• Langage d'atmosphère : Traduisez l'ambiance en descripteurs naturels
• Références de couleurs : Listez les couleurs par nom descriptif + hex
• Prompts de composants : Écrivez 2-3 exemples de prompts qui recréeraient les composants clés dans Stitch
• Directives d'itération : Conseils pour affiner les écrans dans ce design system

Phase 3 : Rédiger le DESIGN.md

Assemblez tout dans le format standard DESIGN.md. Placez-le à .stitch/DESIGN.md dans le répertoire du projet (créez le répertoire .stitch/ s'il n'existe pas).

[!IMPORTANT] Vous DEVEZ inclure le frontmatter YAML en haut du fichier avec le mappage name et colors, exactement comme montré dans l'exemple à examples/DESIGN.md. Ces données structurées sont requises pour que d'autres skills parsent le design system.

Ne pas inclure ce bloc YAML avec au moins les tokens de couleur centraux constitue un échec à utiliser correctement cette skill.

Utilisez le format de l'exemple à examples/DESIGN.md comme votre template. Le fichier doit commencer par le bloc YAML, suivi des sections markdown :

# Design System : [Nom du Projet]
**Project ID :** [Si connu, sinon omettez]

## 1. Thème Visuel et Atmosphère
[Description riche de 2 paragraphes de l'ambiance, la philosophie et les caractéristiques clés]

## 2. Palette de Couleurs et Rôles
### Foundation Primaire
### Accent et Interactif
### Typographie et Hiérarchie de Texte
### États Fonctionnels

## 3. Règles Typographiques
### Hiérarchie et Poids
### Principes d'Espacement

## 4. Stylings de Composants
### Boutons
### Cartes et [Conteneurs Spécifiques au Domaine]
### Navigation
### Inputs et Formulaires
### [Composants Spécifiques au Domaine]

## 5. Principes de Layout
### Grille et Structure
### Stratégie d'Espacement Blanc
### Alignement et Équilibre Visuel
### Comportement Responsif et Touch

## 6. Notes de Design System pour la Génération Stitch
### Langage à Utiliser
### Références de Couleurs
### Prompts de Composants
### Itération Incrémentale

Phase 4 : Intégration (Optionnel)

Si l'utilisateur veut pousser le design system dans Stitch :

1. Remettez à la skill manage-design-system pour les appels MCP create/update
2. Le DESIGN.md que vous avez écrit est l'input — la skill manage-design-system gère l'intégration de l'API Stitch

Si l'utilisateur veut juste le document, vous avez terminé après la Phase 3.

Checklist de Qualité

Avant de livrer le DESIGN.md, vérifiez :

• [ ] Chaque couleur a un nom descriptif, un code hex et un rôle fonctionnel
• [ ] La typographie inclut la famille de police, la description du caractère et la hiérarchie complète
• [ ] Les styles de composants décrivent la forme, la couleur, les états et les transitions
• [ ] Le layout inclut max-width, grille, breakpoints et stratégie d'espacement
• [ ] Les notes de génération Stitch utilisent le langage naturel, pas la syntaxe CSS
• [ ] La section atmosphère se lit comme une copie éditoriale, pas une doc technique
• [ ] Les couleurs quasi-dupliquées sont consolidées
• [ ] Le document capture l'intention derrière le styling, pas juste les valeurs brutes

Conseils pour une Meilleure Extraction

• Lisez les commentaires et les messages de commit. Les développeurs documentent souvent l'intention de design dans les commentaires du code (/* hero section — respirable */) et les messages de commit. C'est de l'or pour comprendre le pourquoi.
• Vérifiez les bibliothèques de design-tokens. Si le projet utilise style-dictionary, @tokens-studio, ou similaire, ces fichiers sont la source la plus autoritaire des valeurs de design.
• Les fichiers de thème ont plus de signal que les styles de composants. Un theme.ts qui définit une palette vous dit le design system prévu ; les styles inline éparpillés dans les composants vous disent ce qui a réellement livré. Les deux comptent, mais commencez par le thème.
• La config Tailwind est un design system. Si un projet a un tailwind.config.js personnalisé, c'est le design system — extrayez-le d'abord, puis validez les composants pour les overrides.
• Les propriétés personnalisées CSS sont intentionnelles. Si un développeur a défini --brand-primary, il vous dit que c'est un design token. Respectez cela.