| 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 :
-
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
-
Documenter la structure de haut niveau :
📁 Nom du DS
├── 📄 Cover / Introduction
├── 📄 Foundations (Colors, Typography, Spacing, Icons...)
├── 📄 Components (Buttons, Inputs, Cards...)
├── 📄 Patterns / Templates
└── 📄 Changelog
-
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…)
-
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 :
- Nom et convention de nommage (PascalCase, kebab-case…)
- Variants : quelles props sont exposées (size, variant, state, color…)
- États : default, hover, active, focus, disabled, loading, error
- Tailles : sm, md, lg (ou XS→2XL)
- Anatomy : parties internes (leading icon, label, trailing icon…)
- Slots : zones de contenu libre (voir étape 3b)
- Composition : dépendances avec d'autres composants
- 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 :
- Une nouvelle entrée dans
## Audits réalisés avec date et lien
- Les nouveaux patterns identifiés dans les sections appropriées
- Les composants ou catégories non encore documentés
- Les conventions de nommage intéressantes
- Les approches de tokens/variables remarquables
- Architecture slots : quels composants utilisent de vrais slots vs legacy
- Pattern d'héritage : quel pattern (A/B/C) est utilisé par famille
- Arbre d'héritage : pour chaque famille en Pattern B, documenter Base → déclinaisons
- Organisation pages : une page par composant / tous sur une page / hybride
- ComponentPageHeader : présent ou non, racine ou imbriqué, props identifiées
- 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
