Design System Builder — Figma MCP Skill

Construisez des systèmes de design 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 systèmes de design (Material 3, Polaris, Figma UI3, Simple DS).

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

Passez toujours skillNames: "figma-generate-library" lors de l'appel à use_figma dans cette skill. C'est un paramètre de logging — il n'affecte pas l'exécution.

1. La seule règle qui compte vraiment

Ce n'est JAMAIS une tâche en un coup. Construire un système de design nécessite 20–100+ appels use_figma sur plusieurs phases, avec des points de contrôle obligatoires entre eux. Toute tentative de créer tout en un seul appel PRODUIRA des résultats cassés, incomplets ou irrécupérables. Décomposez chaque opération en sa plus petite unité utile, validez, recueillez des commentaires, puis procédez.

2. Workflow obligatoire

Chaque construction de système de design suit cet ordre de phase. Sauter ou réordonner les phases provoque des défaillances structurelles coûteuses à corriger.

Phase 0 : DÉCOUVERTE (toujours en premier — aucune écriture use_figma pour l'instant)
  0a. Analyser la base de code → extraire les tokens, composants, conventions de nommage
  0b. Inspecter le fichier Figma → pages, variables, composants, styles, conventions existantes
  0c. Rechercher 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 toute création
  0e. Mapper code → Figma → résoudre les conflits (code et Figma en désaccord = 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 et modes de variables
  1b. Créer des variables primitives (valeurs brutes, 1 mode)
  1c. Créer des variables sémantiques (aliasées aux primitives, conscientes du mode)
  1d. Définir les scopes sur TOUTES les variables
  1e. Définir la syntaxe de code sur TOUTES les variables
  1f. Créer les styles d'effet (ombres) et styles de texte (typographie)
  → Critères de sortie : chaque token du plan convenu existe, tous les scopes définis, toute syntaxe de code 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 page : Cover → Getting Started → Foundations → --- → Components → --- → Utilities
  2b. Créer les pages de documentation des fondations (échantillons de couleur, spécimens typographiques, barres d'espacement)
  → Critères de sortie : toutes les pages planifiées 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 lot)
  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 variants (combineAsVariants + disposition en grille)
    3d. Ajouter les propriétés de composant (TEXT, BOOLEAN, INSTANCE_SWAP)
    3e. Lier les propriétés aux nœuds enfants
    3f. Ajouter la documentation de 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 variants correct, toutes les liaisons vérifiées, la capture d'écran paraît correcte
    ✋ POINT DE CONTRÔLE UTILISATEUR par composant : montrer la capture d'écran, attendre l'approbation avant le prochain composant

Phase 4 : INTÉGRATION + QA (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/contours codés en dur restants)
  4e. Captures d'écran de révision finale de chaque page
  ✋ POINT DE CONTRÔLE UTILISATEUR : approbation complète

3. Règles critiques

Plugin API basics (de la skill use_figma — appliquées ici aussi) :

• Utilisez return pour renvoyer les données (auto-sérialisées). Ne wrappez PAS dans une IIFE ou n'appelez closePlugin.
• Retournez TOUS les IDs de nœud 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émarrage
• figma.notify() lance une exception — ne l'utilisez jamais
• Les couleurs sont dans la plage 0–1, pas 0–255
• La police DOIT être chargée avant toute écriture de texte : await figma.loadFontAsync({family, style}). Utilisez await figma.listAvailableFontsAsync() pour découvrir les polices disponibles et vérifier les chaînes de style exactes — si un chargement échoue, interrogez les polices disponibles pour trouver le nom correct ou une police de secours.

Règles du système de design :

1. Variables AVANT composants — les composants se lient aux variables. Pas de token = pas de composant.
2. Inspecter avant de créer — exécutez use_figma en lecture seule pour découvrir les conventions existantes. Faites-les correspondre.
3. Une page par composant (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 (défaut) — remplissages, contours, padding, rayon, gap. 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 de code sur chaque variable — la syntaxe WEB DOIT utiliser le wrapper var() : var(--color-bg-primary), pas --color-bg-primary. Utilisez le nom de variable CSS réel de la base de code. ANDROID/iOS n'utilisent PAS de wrapper.
7. Alias sémantiques aux primitives — { type: 'VARIABLE_ALIAS', id: primitiveVar.id }. Ne dupliquez jamais les valeurs brutes dans la couche sémantique.
8. Position des variants après combineAsVariants — ils s'empilent à (0,0). Disposition en grille manuelle + redimensionnement.
9. INSTANCE_SWAP pour les icônes — ne créez jamais un variant par icône. Limitez les matrices de variant : si Taille × Style × État > 30 combinaisons, divisez en sous-composant.
10. Nommage déterministe — utilisez des noms de nœud cohérents et uniques pour un nettoyage idempotent et une capacité de reprise. Suivez les IDs de nœud créés via les valeurs de retour et le registre d'état.
11. Pas de nettoyage destructif — les scripts de nettoyage identifient les nœuds par convention de nommage ou par IDs retournés, pas par devinette.
12. Valider avant de procéder — ne construisez jamais 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 de Figma doivent être strictement séquentielles. Même si votre outil supporte les appels parallèles, ne lancez jamais deux appels use_figma simultanément.
14. Ne jamais halluciner les IDs de nœud — lisez toujours les IDs du registre d'état retourné par les appels précédents. Ne reconstruisez jamais ni ne devinez un ID de la mémoire.
15. Utilisez les scripts d'aide — intégrez les scripts de scripts/ dans vos appels use_figma. N'écrivez pas des scripts de 200 lignes à partir de zéro.
16. Approbation de phase explicite — à chaque point de contrôle, nommez explicitement la phase suivante. « Cela paraît bon » n'est pas une approbation de procéder à la Phase 3 si vous aviez demandé à propos de la Phase 1.

4. Gestion d'état (obligatoire pour les workflows longs)

getPluginData() / setPluginData() ne sont PAS supportés dans use_figma. Utilisez getSharedPluginData() / setSharedPluginData() à la place (ceux-ci SONT supportés), ou utilisez les lookups basés sur le nom et le registre d'état (IDs retournés).

Taggez chaque nœud de scène créé immédiatement après la création :

node.setSharedPluginData('dsb', 'run_id', RUN_ID);        // identifie cette exécution de build
node.setSharedPluginData('dsb', 'phase', 'phase3');        // quelle phase l'a créé
node.setSharedPluginData('dsb', 'key', 'component/button');// clé logique unique

Persistance d'état : NE reliez PAS uniquement sur le contexte de conversation pour le registre d'état. Écrivez-le sur le disque :

/tmp/dsb-state-{RUN_ID}.json

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

Maintenez un registre d'état suivant :

{
  "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 : interrogez par nom + ID du registre d'état. S'il existe, sautez ou mettez à jour — ne dupliquez jamais.

Protocole de reprise : au démarrage de la session ou après troncature du contexte, exécutez une use_figma en lecture seule pour balayer toutes les pages, composants, variables et styles par nom pour reconstruire la map {key → id}. Relisez ensuite le fichier d'état du disque si disponible.

Prompt de continuation (donnez-le à l'utilisateur lors de la reprise dans un nouveau chat) :

« Je continue une construction de système de design. ID d'exécution : {RUN_ID}. Chargez la skill figma-generate-library et reprenez à partir de la dernière étape complétée. »

5. search_design_system — Matrice de décision de réutilisation

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

search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

Réutilisez si tous les critères suivants sont vrais :

• L'API de propriété de composant correspond à vos besoins (mêmes axes de variant, types compatibles)
• Le modèle de liaison de token est compatible (utilise les mêmes variables ou des variables 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)

Reconstruisez si l'un des critères suivants :

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

Wrappez si correspondance visuelle mais API incompatible :

• Importez le composant de bibliothèque en tant qu'instance imbriquée dans un nouveau composant wrapper
• Exposez une API propre sur le wrapper

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

6. Points de contrôle utilisateur

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

Si l'utilisateur rejette : corriger avant de continuer. Ne construisez jamais sur du travail rejeté.

7. Conventions de nommage

Faites correspondre les conventions existantes du fichier. Si vous commencez à zéro :

Variables (séparées par des slashes) :

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 variants : Property=Value, Property=Value — p. ex., Size=Medium, Style=Primary, State=Default

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

Référence de nommage complète : 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 quelque chose avant que la portée soit verrouillée avec l'utilisateur
• ❌ Ignorer les conventions existantes du fichier et en imposer de nouvelles
• ❌ Sauter 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 de créer des alias
• ❌ Ne pas définir la syntaxe de code (casse Dev Mode et la synchronisation bidirectionnelle)
• ❌ Créer des tokens de composants avant d'accepter la taxonomie des tokens

Anti-patterns de Phase 2 :

• ❌ Sauter 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 des composants avant que les fondations existent
• ❌ Coder en dur une valeur de remplissage/contour/espacement/rayon dans un composant
• ❌ Créer un variant par icône (utilisez INSTANCE_SWAP à la place)
• ❌ Ne pas positionner les variants après combineAsVariants (ils s'empilent tous à 0,0)
• ❌ Construire une matrice de variant > 30 sans diviser (explosion de variants)
• ❌ Importer des composants distants puis les détacher immédiatement

Anti-patterns généraux :

• ❌ Réessayer un script qui a échoué sans comprendre l'erreur d'abord
• ❌ Utiliser le matching par 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
• ❌ Sauter 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œud de la mémoire (toujours lire du registre d'état)
• ❌ Écrire des scripts inlines massifs au lieu d'utiliser les scripts d'aide fournis
• ❌ Commencer la Phase 3 parce que l'utilisateur a dit « constuis le bouton » sans compléter les Phases 0-2

10. Documents de référence

Chargez à la demande — chaque référence est autoritaire pour sa phase :

Utilisez votre outil de lecture de fichier pour lire ces docs si nécessaire. Ne supposez pas leur contenu à partir du nom de fichier.

11. Scripts

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