Design System Builder — Figma MCP Skill

Construisez des design systems professionnels dans Figma qui correspondent au code. Cette skill orchestre des workflows multi-phases sur 20–100+ appels use_figma, en appliquant des patterns de qualité issus de vrais design systems (Material 3, Polaris, Figma UI3, Simple DS).

Prérequis : la skill figma-use DOIT également être chargée pour chaque appel use_figma. Elle fournit les règles de syntaxe de l'API Plugin (pattern de retour, réinitialisation de page, retour d'ID, chargement de police, gamme de couleurs). Cette skill fournit la connaissance du domaine des design systems et l'orchestration de workflows.

Incluez toujours figma-generate-library dans le paramètre skillNames séparé par des virgules lorsque vous appelez use_figma comme partie de cette skill. Si cette skill a été chargée via une ressource MCP, vous DEVEZ préfixer le nom avec resource: (p. ex. resource:figma-generate-library). C'est un paramètre de journalisation — il n'affecte pas l'exécution.

1. La Seule Règle Qui Compte Vraiment

Ce n'est JAMAIS une tâche à une seule étape. Construire un design system nécessite 20–100+ appels use_figma sur plusieurs phases, avec des points de contrôle utilisateur obligatoires entre eux. Toute tentative de créer tout en un seul appel PRODUIRA des résultats cassés, incomplets ou irrécupérables. Divisez chaque opération en la plus petite unité utile, validez, obtenez du feedback, procédez.

2. Workflow Obligatoire

Chaque construction de design system suit cet ordre de phases. Ignorer ou réordonner les phases cause des défaillances structurelles coûteuses à annuler.

Phase 0 : DÉCOUVERTE (toujours en premier — pas encore d'écritures use_figma)
  0a. Analyser la codebase → extraire les tokens, composants, conventions de nommage
  0b. Inspecter le fichier Figma → pages, variables, composants, styles, conventions existantes
  0c. Rechercher dans les bibliothèques abonnées → utiliser search_design_system pour les assets réutilisables
  0d. Verrouiller la portée v1 → s'accorder sur l'ensemble exact des tokens + liste de composants avant création
  0e. Mapper code → Figma → résoudre les conflits (code et Figma ne correspondent pas = demander à l'utilisateur)
  ✋ POINT DE CONTRÔLE UTILISATEUR : présenter le plan complet, attendre l'approbation explicite

Phase 1 : FONDATIONS (tokens d'abord — toujours avant les composants)
  1a. Créer les collections de variables et les modes
  1b. Créer les variables primitives (valeurs brutes, 1 mode)
  1c. Créer les variables sémantiques (aliasées aux primitives, sensibles aux modes)
  1d. Définir les scopes sur TOUTES les variables
  1e. Définir la syntaxe du code sur TOUTES les variables
  1f. Créer les styles d'effet (ombres) et les styles de texte (typographie)
  → Critères de sortie : chaque token du plan convenu existe, tous les scopes sont définis, toute la syntaxe du code est définie
  ✋ POINT DE CONTRÔLE UTILISATEUR : montrer le résumé des variables, attendre l'approbation

Phase 2 : STRUCTURE DE FICHIER (avant les composants)
  2a. Créer le squelette de pages : Cover → Getting Started → Foundations → --- → Components → --- → Utilities
  2b. Créer les pages de documentation des fondations (nuanciers, spécimens typographiques, barres d'espacement)
  → Critères de sortie : toutes les pages prévues existent, les docs des fondations sont navigables
  ✋ POINT DE CONTRÔLE UTILISATEUR : montrer la liste des pages + capture d'écran, attendre l'approbation

Phase 3 : COMPOSANTS (un à la fois — jamais par lots)
  Pour CHAQUE composant (dans l'ordre des dépendances : atomes avant molécules) :
    3a. Créer une page dédiée
    3b. Construire le composant de base avec auto-layout + liaisons de variables complètes
    3c. Créer toutes les combinaisons de variantes (combineAsVariants + disposition en grille)
    3d. Ajouter les propriétés des composants (TEXT, BOOLEAN, INSTANCE_SWAP)
    3e. Lier les propriétés aux nœuds enfants
    3f. Ajouter la documentation de la page (titre, description, notes d'utilisation)
    3g. Valider : get_metadata (structure) + get_screenshot (visuel)
    3h. Optionnel : mappage Code Connect léger pendant que le contexte est frais
    → Critères de sortie : nombre de variantes correct, toutes les liaisons vérifiées, la capture d'écran semble correcte
    ✋ POINT DE CONTRÔLE UTILISATEUR par composant : montrer la capture d'écran, attendre l'approbation avant le composant suivant

Phase 4 : INTÉGRATION + AQ (passage final)
  4a. Finaliser tous les mappages Code Connect
  4b. Audit d'accessibilité (contraste, cibles tactiles min, visibilité du focus)
  4c. Audit de nommage (pas de doublons, pas de nœuds sans nom, casse cohérente)
  4d. Audit des liaisons non résolues (pas de remplissages/traits codés en dur restants)
  4e. Captures d'écran finales de chaque page
  ✋ POINT DE CONTRÔLE UTILISATEUR : signature complète

3. Règles Critiques

Bases de l'API Plugin (de la skill use_figma — appliquées ici aussi) :

• Utiliser return pour renvoyer les données (sérialisation automatique). Ne PAS envelopper dans une IIFE ou appeler closePlugin.
• Retourner TOUS les IDs de nœuds créés/mutés dans chaque valeur de retour
• Le contexte de page se réinitialise à chaque appel — toujours await figma.setCurrentPageAsync(page) au début. L'appeler au maximum une fois par script : chaque composant ou page de doc est son propre appel use_figma. Ne jamais boucler sur figma.root.children et basculer entre les pages dans un script mutant — divisez ce travail en un appel ciblé par page cible (voir figma-use → gotchas.md → Set current page once per use_figma call)
• figma.notify() lève une erreur — ne jamais l'utiliser
• Les couleurs sont en plage 0–1, pas 0–255
• La police DOIT être chargée avant toute écriture de texte : await figma.loadFontAsync({family, style}). Utiliser await figma.listAvailableFontsAsync() pour découvrir les polices disponibles et vérifier les chaînes de style exactes — si un chargement échoue, interroger les polices disponibles pour trouver le nom correct ou un fallback.

Règles des design systems :

1. Variables AVANT les composants — les composants se lient aux variables. Pas de token = pas de composant.
2. Inspecter avant de créer — exécuter des use_figma en lecture seule pour découvrir les conventions existantes. Les correspondre.
3. Une page par composant (par défaut) — exception : les familles étroitement liées (p. ex., Input + helpers) peuvent partager une page avec une séparation de section claire.
4. Lier les propriétés visuelles aux variables (par défaut) — remplissages, traits, padding, rayon, gap. Dans $fig, lier en passant le handle de variable directement dans la propriété (fills couleur, cornerRadius, itemSpacing, padding) ; chaque fois qu'un token existe pour une valeur, préférer le lier à un littéral (recette travaillée). Parce que les composants sont généralement construits dans un appel use_figma séparé de la base de tokens, réhydrater les IDs de variable dans l'appel de construction (figma.variables.getVariableByIdAsync / $fig.getVar) avant la liaison — les handles ne survivent pas d'un appel à l'autre, et ignorer ceci est pourquoi une construction retombe silencieusement sur les littéraux. Exceptions : géométrie intentionnellement fixe (tailles de grille de pixels d'icône, séparateurs statiques).
5. Scopes sur chaque variable — NE JAMAIS laisser comme ALL_SCOPES. Arrière-plan : FRAME_FILL, SHAPE_FILL. Texte : TEXT_FILL. Bordure : STROKE_COLOR. Espacement : GAP. Rayons : CORNER_RADIUS. Primitives : [] (caché).
6. Syntaxe du code sur chaque variable — la syntaxe WEB DOIT utiliser le wrapper var() : var(--color-bg-primary), pas --color-bg-primary. Utiliser le nom de variable CSS réel de la codebase. ANDROID/iOS ne PAS utiliser de wrapper.
7. Alias des variables sémantiques aux primitives — { type: 'VARIABLE_ALIAS', id: primitiveVar.id }. Ne jamais dupliquer les valeurs brutes dans la couche sémantique.
8. Positionner les variantes après combineAsVariants — elles s'empilent à (0,0). Disposition en grille manuelle + redimensionner.
9. INSTANCE_SWAP pour les icônes — ne jamais créer une variante par icône. Plafonner les matrices de variantes : si Taille × Style × État > 30 combinaisons, diviser en sous-composant.
10. Nommage déterministe — utiliser des noms de nœuds cohérents et uniques pour un nettoyage idempotent et une capacité de reprise. Suivre les IDs de nœuds créés via les valeurs de retour et le registre d'état.
11. Pas de nettoyage destructeur — les scripts de nettoyage identifient les nœuds par convention de nommage ou par IDs retournés, pas en devinant.
12. Valider avant de procéder — ne jamais construire sur du travail non validé. get_metadata après chaque création, get_screenshot après chaque composant.
13. NE JAMAIS paralléliser les appels use_figma — les mutations d'état Figma doivent être strictement séquentielles. Même si votre outil supporte les appels parallèles, ne jamais exécuter deux appels use_figma simultanément.
14. Ne jamais halluciner les IDs de nœuds — toujours lire les IDs du registre d'état retournés par les appels précédents. Ne jamais reconstruire ou deviner un ID de la mémoire.
15. Utiliser les scripts d'aide — intégrer les scripts de scripts/ dans vos appels use_figma. Ne pas écrire des scripts inline de 200 lignes à partir de zéro.
16. Approbation de phase explicite — à chaque point de contrôle, nommer la phase suivante explicitement. « c'est bon » n'est pas une approbation pour procéder à la Phase 3 si vous aviez demandé à propos de la Phase 1.

4. Gestion d'État (Obligatoire pour les Workflows Longs)

Ne pas stocker l'état du workflow sur les objets Figma. Utiliser des noms déterministes pour la découverte et des IDs retournés exacts dans le registre d'état. Mettre des conseils de but de composant lisibles et des conseils d'utilisation dans la description du composant ou du composant-set.

Enregistrer chaque ID retourné dans le registre d'état immédiatement après la création. Ne jamais utiliser une recherche floue pour autoriser une suppression.

Persistance d'état : NE PAS s'appuyer uniquement sur le contexte de conversation pour le registre d'état. L'écrire sur le disque :

/tmp/design-system-state-{RUN_ID}.json

Le relire au début de chaque tour. Dans les workflows longs, le contexte de conversation sera tronqué — le fichier est la source de vérité.

Maintenir un registre d'état suivi :

{
  "runId": "ds-build-2024-001",
  "phase": "phase3",
  "step": "component-button",
  "entities": {
    "collections": { "primitives": "id:...", "color": "id:..." },
    "variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },
    "pages": { "Cover": "id:...", "Button": "id:..." },
    "components": { "Button": "id:..." }
  },
  "pendingValidations": ["Button:screenshot"],
  "completedSteps": ["phase0", "phase1", "phase2", "component-avatar"]
}

Vérification d'idempotence avant chaque création : interroger par nom + ID du registre d'état. Si existe, ignorer ou mettre à jour — ne jamais dupliquer.

Protocole de reprise : au démarrage de la session ou après troncature de contexte, exécuter un use_figma en lecture seule pour analyser toutes les pages, composants, variables et styles par nom pour reconstruire la map {clé → id}. Puis relire le fichier d'état du disque s'il est disponible.

Prompt de continuation (donner ceci à l'utilisateur lors de la reprise dans un nouveau chat) :

« Je reprends une construction de design system. Run ID : {RUN_ID}. Chargez la skill figma-generate-library et reprenez à partir de la dernière étape complétée. »

5. Découverte de Bibliothèque et search_design_system — Matrice de Décision de Réutilisation

Rechercher D'ABORD en Phase 0, puis à nouveau immédiatement avant chaque création de composant.

Commencer par get_libraries pour comprendre quelles bibliothèques sont disponibles avant de chercher à l'aveugle :

// Découvrir toutes les bibliothèques accessibles au fichier
get_libraries({ fileKey })
// Retour :
//   libraries_added_to_file: [{ name, libraryKey, description, source }, ...]
//   libraries_available_to_add: [{ name, libraryKey, description, source }, ...]
//   libraries_available_to_add_next_offset: number | null

Utiliser les valeurs libraryKey retournées pour limiter les recherches à des bibliothèques spécifiques via includeLibraryKeys. Ceci évite des résultats bruyants quand de nombreuses bibliothèques sont disponibles.

Si libraries_available_to_add_next_offset n'est pas nul, plus de bibliothèques org sont disponibles — appeler get_libraries à nouveau avec offset défini sur cette valeur. Les bibliothèques org se paginent par lots de 20 ; les kits UI communautaires n'apparaissent que sur la première page.

// Rechercher dans toutes les bibliothèques (par défaut)
search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

// Rechercher au sein d'une bibliothèque spécifique uniquement
search_design_system({ query, fileKey, includeLibraryKeys: ["lk-abc123..."], includeComponents: true })

Réutiliser si tous ces éléments sont vrais :

• L'API de propriété du composant correspond à vos besoins (mêmes axes de variante, types compatibles)
• Le modèle de liaison de token est compatible (utilise les mêmes variables ou aliasables)
• Les conventions de nommage correspondent au fichier cible
• Le composant est éditable (pas verrouillé dans une bibliothèque distante que vous ne possédez pas)

Reconstruire si l'un de ces éléments :

• Incompatibilité d'API (noms de propriétés différents, mauvais modèle de variante)
• Modèle de token incompatible (valeurs codées en dur, schéma de variables différent)
• Problème de propriété (ne peut pas modifier la bibliothèque)

Envelopper si correspondance visuelle mais API incompatible :

• Importer le composant de bibliothèque comme instance imbriquée dans un nouveau composant enveloppe
• Exposer une API propre sur l'enveloppe

Priorité trois voies : existant local → import de bibliothèque abonnée → créer nouveau.

6. Points de Contrôle Utilisateur

Obligatoires. Les décisions de conception nécessitent un jugement humain.

Si l'utilisateur rejette : corriger avant de procéder. Ne jamais construire sur du travail rejeté.

7. Conventions de Nommage

Correspondre aux conventions de fichier existantes. Si commencer de zéro :

Variables (séparées par des barres obliques) :

color/bg/primary     color/text/secondary    color/border/default
spacing/xs  spacing/sm  spacing/md  spacing/lg  spacing/xl  spacing/2xl
radius/none  radius/sm  radius/md  radius/lg  radius/full
typography/body/font-size    typography/heading/line-height

Primitives : blue/50 → blue/900, gray/50 → gray/900

Noms de composants : Button, Input, Card, Avatar, Badge, Checkbox, Toggle

Noms de variantes : Property=Value, Property=Value — p. ex., Size=Medium, Style=Primary, State=Default

Séparateurs de pages : --- (le plus courant) ou ——— COMPONENTS ———

Référence de nommage complet : naming-conventions.md

8. Architecture des Tokens

Pattern standard (point de départ recommandé) :

Collection : "Primitives"    modes : ["Value"]
  blue/500 = #3B82F6, gray/900 = #111827, ...

Collection : "Color"         modes : ["Light", "Dark"]
  color/bg/primary → Light : alias Primitives/white, Dark : alias Primitives/gray-900
  color/text/primary → Light : alias Primitives/gray-900, Dark : alias Primitives/white

Collection : "Spacing"       modes : ["Value"]
  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...

9. Anti-Patterns par Phase

Anti-patterns de Phase 0 :

• ❌ Commencer à créer quoi que ce soit avant que la portée soit verrouillée avec l'utilisateur
• ❌ Ignorer les conventions de fichier existantes et en imposer de nouvelles
• ❌ Ignorer search_design_system avant de planifier la création de composants

Anti-patterns de Phase 1 :

• ❌ Utiliser ALL_SCOPES sur n'importe quelle variable
• ❌ Dupliquer les valeurs brutes dans la couche sémantique au lieu d'aliaser
• ❌ Ne pas définir la syntaxe du code (casse le Dev Mode et le round-tripping)
• ❌ Créer les tokens des composants avant d's'accorder sur la taxonomie des tokens

Anti-patterns de Phase 2 :

• ❌ Ignorer la page de couverture ou les docs des fondations
• ❌ Mettre plusieurs composants non liés sur une page

Anti-patterns de Phase 3 :

• ❌ Créer les composants avant que les fondations existent
• ❌ Coder en dur n'importe quelle valeur de remplissage/trait/padding/rayon dans un composant
• ❌ Créer une variante par icône (utiliser INSTANCE_SWAP à la place)
• ❌ Ne pas positionner les variantes après combineAsVariants (elles s'empilent toutes à 0,0)
• ❌ Construire une matrice de variantes > 30 sans diviser (explosion de variantes)
• ❌ Importer des composants distants puis les détacher immédiatement

Anti-patterns généraux :

• ❌ Réessayer un script échoué sans d'abord comprendre l'erreur
• ❌ Utiliser la correspondance de préfixe de nom pour le nettoyage (supprime les nœuds appartenant à l'utilisateur)
• ❌ Construire sur du travail non validé de l'étape précédente
• ❌ Ignorer les points de contrôle utilisateur pour « gagner du temps »
• ❌ Paralléliser les appels use_figma (toujours séquentiels)
• ❌ Deviner/halluciner les IDs de nœuds de la mémoire (toujours lire du registre d'état)
• ❌ Écrire des scripts inline massifs au lieu d'utiliser les scripts d'aide fournis
• ❌ Commencer la Phase 3 parce que l'utilisateur a dit « construis le bouton » sans compléter les Phases 0-2

10. Docs de Référence

Charger à la demande — chaque référence est l'autorité pour sa phase :

Utiliser votre outil de lecture de fichier pour lire ces docs au besoin. Ne pas supposer leurs contenus d'après le nom de fichier.

11. Scripts

Fonctions d'aide réutilisables de l'API Plugin. Intégrer dans les appels use_figma :