ds-audit

name	ds-audit
description	Rétro-ingénierie de Design Systems Figma. USE WHEN: l'utilisateur fournit un lien Figma Community, veut analyser un DS existant, extraire la structure des composants, les tokens, les patterns d'organisation. Construit progressivement une base de connaissances DS.
argument-hint	URL Figma Community du Design System à analyser

DS Audit — Rétro-ingénierie de Design Systems Figma

Objectif

Analyser un Design System publié sur Figma Community pour en extraire :

• La structure d'organisation (pages, sections, frames)
• L'inventaire complet des composants
• L'architecture des tokens (variables, styles)
• Les patterns de présentation et de documentation
• Les conventions de nommage

Chaque audit enrichit la base de connaissances DS.

Consulter la documentation Figma pour les concepts clés (slots, héritage cascade, props).

Procédure

Étape 1 — Récupération des métadonnées

Extraire fileKey de l'URL Figma fournie, puis :

1. Appeler mcp_figma_get_metadata avec le fileKey pour obtenir :

   • Nom du fichier et description
   • Liste des pages
   • Arborescence des frames/sections principales
   • Nombre de composants et styles

2. Documenter la structure de haut niveau :

   📁 Nom du DS
   ├── 📄 Cover / Introduction
   ├── 📄 Foundations (Colors, Typography, Spacing, Icons...)
   ├── 📄 Components (Buttons, Inputs, Cards...)
   ├── 📄 Patterns / Templates
   └── 📄 Changelog
   

3. Identifier l'organisation des pages composants :

   • Une page par composant ? (Button, Input, Card… en pages séparées)
   • Tous sur une page ? (Components avec des sections)
   • Hybride ? (Pages par catégorie : Actions, Inputs…)

4. Détecter un ComponentPageHeader :

   • Y a-t-il un header récurrent en haut de chaque page/section de composant ?
   • Est-ce un Main Component réutilisé (instance) ou du texte libre ?
   • Quelles infos contient-il ? (nom, description, statut, tags, version…)
   • Est-il à la racine du fichier ou imbriqué ?

Étape 2 — Analyse des variables/tokens

⚠️ Limitation Community : Les fichiers Figma Community ne partagent généralement PAS leurs variables. get_variable_defs retournera peu ou rien. Seuls les fichiers dont on est propriétaire/éditeur exposent l'intégralité des tokens. Dans ce cas, se rabattre sur le get_design_context des composants pour déduire les tokens depuis le code CSS généré.

Appeler mcp_figma_get_variable_defs sur plusieurs nodeIds (page racine + composants clés) pour maximiser les résultats. Extraire :

• Couleurs : primitives (palette) vs sémantiques (foreground, background, border, etc.)
• Typographie : familles, tailles, poids, line-height
• Espacement : échelle de spacing (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px…)
• Arrondis : border-radius (none, sm, md, lg, xl, full)
• Ombres : elevation levels
• Breakpoints : si définis
• Sizing composants : controlHeight, paddings, gaps (voir Étape 2b)

Documenter le schéma de nommage des tokens :

{category}/{property}/{variant}/{state}
Exemple : color/background/primary/default

Évaluer la qualité du naming — Référence : Ant Design 5.10 (gold standard)

Qualité	Exemple	Verdict
✅ Sémantique	Primary/colorPrimary, Space/Padding/paddingSM	Lisible, maintenable
⚠️ Semi-sémantique	primary/9, Body/size	Acceptable
❌ Cryptique	CP/9, GREY/1	Nécessite documentation, risque d'erreur

Étape 2b — Vérification des tokens de sizing interactifs ⚠️ CRITIQUE

Pour les composants interactifs (Button, Input, Select…), vérifier que les dimensions NE SONT PAS hardcodées mais passent par des tokens :

Propriété	Token attendu	Exemple Ant Design	Anti-pattern
Hauteur bouton	controlHeight/{size}	controlHeightSM=24, controlHeight=32, controlHeightLG=40	h-[43px] hardcodé
Padding horizontal	padding/{size}	paddingSM=8, padding=12, paddingLG=16	px-[14px] hardcodé
Gap icône/texte	margin/{size}	marginXS=8	gap-[4px] hardcodé
Taille icône	fontSize/{size}	lié au fontSize	w-[16px] hardcodé
Border radius	borderRadius	borderRadius=6	✅ souvent tokenisé

Comment vérifier : appeler get_design_context sur le composant Button et chercher dans le code CSS si les valeurs sont des var(--token) ou des littéraux px. Si littéraux → flag comme lacune dans la synthèse.

Étape 3 — Inventaire des composants

Pour chaque page de composants, appeler mcp_figma_get_screenshot sur les sections clés, puis analyser :

Classification des composants

Catégorie	Exemples typiques
Actions	Button, IconButton, FAB, Link
Inputs	TextField, TextArea, Select, Checkbox, Radio, Switch, Slider, DatePicker
Navigation	Navbar, Sidebar, Tabs, Breadcrumb, Pagination, Menu
Data Display	Table, List, Card, Badge, Avatar, Tag/Chip, Tooltip
Feedback	Alert, Toast/Snackbar, Dialog/Modal, Progress, Skeleton
Layout	Container, Grid, Stack, Divider, Spacer
Overlay	Popover, Dropdown, Drawer, Sheet
Media	Image, Icon, Video

⚠️ Layouts : Analyser spécifiquement si les composants de layout sont des conteneurs slot-based (on compose dedans librement) ou des templates figés (mise en page prédéfinie rigide). Cf. Étape 3d.

Pour chaque composant, noter :

1. Nom et convention de nommage (PascalCase, kebab-case…)
2. Variants : quelles props sont exposées (size, variant, state, color…)
3. États : default, hover, active, focus, disabled, loading, error
4. Tailles : sm, md, lg (ou XS→2XL)
5. Anatomy : parties internes (leading icon, label, trailing icon…)
6. Slots : zones de contenu libre (voir étape 3b)
7. Composition : dépendances avec d'autres composants
8. Héritage : est-ce un composant Base ou une déclinaison ? (voir étape 3c)

Étape 3b — Analyse des Slots ⚠️ CRITIQUE

Les slots sont une fonctionnalité récente de Figma. Sur 10 DS audités, seulement 2 utilisent de vrais slots natifs (Slot Components, Starter UI). La majorité utilise encore boolean toggles + instance swap. Il faut détecter le pattern réel ET recommander la migration si legacy.

Cf. documentation Figma — section Slots pour les détails.

Détection

Pour chaque composant, identifier les zones de contenu interchangeable :

Ce qu'on cherche	Comment le détecter	Classification
Calque nommé ⬦ Slot	Métadonnées / screenshot	✅ Vrai slot
Instance swap avec preferredValues larges	Props du composant	⚠️ Proto-slot (legacy)
Boolean toggle d'icône (show/hide)	Props booléennes	❌ Pattern rigide
Frame conteneur avec contraintes	Structure interne	🔄 Slot implicite

Cartographie des slots par composant

Pour chaque composant, documenter :

### Button
- **leading** : [slot/swap/boolean] → icône ou contenu avant le label
- **content** : [slot/text] → label principal
- **trailing** : [slot/swap/boolean] → icône ou contenu après le label
→ Recommandation : convertir en vrais slots si legacy

Recommandation systématique

Si le DS utilise l'ancienne méthode (boolean + instance swap) :

• Recommander la migration vers des vrais slots
• Mapper : showIcon=true + icon=swap → leading: ReactNode
• Documenter la correspondance ancien→nouveau dans la synthèse

Étape 3c — Analyse de l'héritage en cascade

Cf. documentation Figma — section Héritage pour les détails.

Identifier le pattern d'héritage utilisé par chaque famille de composants :

Pattern A — Tout en variants (flat) ⭐ DOMINANT

Button (Main Component unique)
  └── Variant: Primary | Secondary | Ghost | Danger
  └── Variant: Size SM | MD | LG
  └── Variant: State Default | Hover | Disabled

→ Composant unique avec beaucoup de variants. Simple mais rigide. → Pattern le plus courant : observé dans 7/10 DS audités.

Pattern A+ — Flat + Wrapper externe

Buttons variant (Component Set — Type × State, PAS de Size)
4Button main (Wrapper — Size only, contient instance de Buttons variant)

→ Sépare les axes visuels (type/state) de l'axe dimensionnel (size). → Observé dans DS Arnaud. Complexe, maintenance fragile (2 composants à synchroniser).

Pattern B — Héritage en cascade (aspirationnel)

ButtonBase (Main Component)
  ├── structure commune + props de base
  │
  ├── ButtonPrimary → instance de Base + overrides couleur
  ├── ButtonSecondary → instance de Base + overrides couleur
  ├── ButtonGhost → instance de Base + overrides transparence
  └── ButtonDanger → instance de Base + overrides couleur

→ Le changement de structure sur Base se propage partout. Pattern préféré en théorie. → ⚠️ Jamais observé dans les 10 DS audités. Ce pattern reste l'idéal pour le code (ButtonBase.tsx → ButtonPrimary.tsx) mais n'est pas pratiqué côté Figma dans la wild.

Pattern C — Composants indépendants (découplé)

ButtonPrimary (Main Component)
ButtonSecondary (Main Component)
ButtonGhost (Main Component)

→ Aucun lien entre eux. Maintenance difficile. Anti-pattern.

Pour chaque famille, documenter :

Famille	Pattern	Base Component	Nb déclinaisons	Props héritées	Overrides par déclinaison
Button	A/B/C	ButtonBase	4	size, state	fill, text, border
Input	A/B/C	InputBase	3	size, state	border, bg

Étape 4 — Analyse des patterns de présentation

Observer comment le DS présente ses composants :

• Component Page Header : y a-t-il un header récurrent ? Est-ce un composant réutilisable ?
  • Si oui : documenter ses props (title, description, status, metadata…)
  • Est-il à la racine du fichier ou imbriqué dans chaque page ?
• Showcase frame : tous les variants dans une grille
• Anatomy frame : éclaté avec annotations
• Do/Don't : exemples d'usage correct/incorrect
• Specs frame : dimensions, espacements, mesures
• Usage guidelines : texte explicatif intégré

Étape 4b — Analyse des Layouts

Identifier comment le DS traite les layouts :

Ce qu'on cherche	Classification
Composants layout avec slots (header, sidebar, content, footer)	✅ Slot-based (recommandé)
Page "Layouts" avec templates figés (Dashboard, Settings, Profile…)	⚠️ Templates statiques
Pas de composants layout, juste des frames	❌ Pas de système layout

Pour chaque composant layout trouvé, documenter :

Layout	Slots identifiés	Type (slot/figé)	Composable ?
PageLayout	header, sidebar, content, footer	slot / figé	oui / non
CardLayout	media, header, content, actions	slot / figé	oui / non
…	…	…	…

Recommandation systématique :

• Si templates figés → recommander la conversion en composants slot-based
• Si pas de système layout → recommander la création de PageLayout, SectionLayout, GridLayout, StackLayout

Étape 5 — Mise à jour de la base de connaissances

Ouvrir ds-knowledge-base.md et ajouter :

1. Une nouvelle entrée dans ## Audits réalisés avec date et lien
2. Les nouveaux patterns identifiés dans les sections appropriées
3. Les composants ou catégories non encore documentés
4. Les conventions de nommage intéressantes
5. Les approches de tokens/variables remarquables
6. Architecture slots : quels composants utilisent de vrais slots vs legacy
7. Pattern d'héritage : quel pattern (A/B/C) est utilisé par famille
8. Arbre d'héritage : pour chaque famille en Pattern B, documenter Base → déclinaisons
9. Organisation pages : une page par composant / tous sur une page / hybride
10. ComponentPageHeader : présent ou non, racine ou imbriqué, props identifiées
11. Layouts : slot-based / templates figés / absents — quels slots par layout

Étape 6 — Synthèse

Produire un résumé structuré :

## Audit : [Nom du DS]
- **Fichier** : [lien Figma]
- **Date** : YYYY-MM-DD
- **Pages** : X pages | Y composants | Z variables
- **Stack tokens** : [type de structure]
- **Points forts** : ...
- **Patterns intéressants** : ...
- **Composants remarquables** : ...

Règles

• Ne JAMAIS modifier les analyses précédentes dans la base de connaissances — seulement ajouter
• Toujours dater les entrées
• Comparer systématiquement avec les audits précédents pour noter les patterns récurrents
• Si un pattern apparaît dans 3+ DS audités, le marquer comme pattern commun
• Utiliser les screenshots Figma pour valider la structure visuelle
• Toujours analyser les slots même si absents — recommander leur adoption si legacy (seulement 2/10 DS utilisent des vrais slots)
• Toujours identifier le pattern d'héritage (A/A+/B/C) pour chaque famille de composants
• Mentionner le Pattern B comme cible idéale côté code, mais noter que le Pattern A domine côté Figma
• Toujours vérifier les tokens de sizing (Étape 2b) — heights, paddings, gaps des composants interactifs
• Toujours détecter le ComponentPageHeader — noter s'il est réutilisable et à la racine
• Toujours analyser les layouts — vérifier s'ils sont slot-based ou figés
• Recommander layouts slot-based si templates figés ou absents
• Si fichier Community : s'attendre à des variables limitées, utiliser get_design_context comme plan B
• Tester plusieurs nodeIds si le premier ne retourne rien — essayer les pages principales, les composants clés