Générateur de système de conception — Compétence Figma MCP

Construisez des systèmes de conception de qualité professionnelle dans Figma qui correspondent au code. Cette compétence orchestre des flux de travail multiphases sur 20–100+ appels use_figma, en appliquant les modèles de qualité provenant de systèmes de conception réels (Material 3, Polaris, Figma UI3, Simple DS).

Conditions préalables : La compétence figma-use DOIT également être chargée pour chaque appel use_figma. Elle fournit les règles de syntaxe de l'API Plugin (modèle de retour, réinitialisation de page, retour d'ID, chargement de police, plage de couleurs). Cette compétence fournit les connaissances du domaine du système de conception et l'orchestration du flux de travail.

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

1. La seule règle qui importe vraiment

Ce n'est JAMAIS une tâche ponctuelle. Construire un système de conception 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 des retours, procédez.

2. Flux de travail obligatoire

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

Phase 0 : DÉCOUVERTE (toujours en premier — pas encore d'écritures use_figma)
  0a. Analyser la base de code → extraire les jetons, les composants, les 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 actifs réutilisables
  0d. Verrouiller la portée v1 → convenir de l'ensemble exact de jetons + liste de composants avant toute création
  0e. Mapper le code → Figma → résoudre les conflits (le code et Figma ne concordent pas = demander à l'utilisateur)
  ✋ POINT DE CONTRÔLE UTILISATEUR : présenter le plan complet, attendre l'approbation explicite

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

Phase 2 : STRUCTURE DES FICHIERS (avant les composants)
  2a. Créer le squelette de la page : 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 planifiées existent, les documents de fondations sont navigables
  ✋ POINT DE CONTRÔLE UTILISATEUR : afficher la liste des pages + capture d'écran, attendre l'approbation

Phase 3 : COMPOSANTS (un à la fois — jamais en lot)
  Pour CHAQUE composant (en ordre de dépendance : les atomes avant les molécules) :
    3a. Créer une page dédiée
    3b. Construire le composant de base avec auto-layout + liaisons complètes de variables
    3c. Créer toutes les combinaisons de variantes (combineAsVariants + disposition en grille)
    3d. Ajouter des propriétés de composant (TEXT, BOOLEAN, INSTANCE_SWAP)
    3e. Lier les propriétés aux nœuds enfants
    3f. Ajouter une documentation de page (titre, description, notes d'utilisation)
    3g. Valider : get_metadata (structure) + get_screenshot (visuel)
    3h. Optionnel : mappage léger de Code Connect 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 : afficher la capture d'écran, attendre l'approbation avant le prochain composant

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

3. Règles critiques

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

• Utiliser return pour renvoyer des données (sérialisation automatique). NE PAS envelopper dans une IIFE ou appeler closePlugin.
• Retourner TOUS les ID 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() lève une exception — ne jamais l'utiliser
• 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})

Règles du système de conception :

1. Variables AVANT les composants — les composants se lient aux variables. Pas de jeton = pas de composant.
2. Inspecter avant de créer — exécuter une use_figma en lecture seule pour découvrir les conventions existantes. Les respecter.
3. Une page par composant (par défaut) — exception : les familles étroitement liées (par exemple, 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) — rembourrages, traits, remplissages, rayons, espaces. Exceptions : géométrie intentionnellement fixe (tailles de grille de pixels d'icône, diviseurs statiques).
5. Portées sur chaque variable — NE JAMAIS laisser en tant que ALL_SCOPES. Contexte : FRAME_FILL, SHAPE_FILL pour l'arrière-plan. Texte : TEXT_FILL. Bordure : STROKE_COLOR. Espacement : GAP. Rayons : CORNER_RADIUS. Primitives : [] (masquées).
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 base de code. ANDROID/iOS N'utilisent PAS de wrapper.
7. Aliaser la sémantique 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 manuelle en grille + redimensionner.
9. INSTANCE_SWAP pour les icônes — ne jamais créer une variante par icône. Limiter les matrices de variantes : si Size × Style × State > 30 combinaisons, diviser en sous-composant.
10. Nommage déterministe — utiliser des noms de nœud cohérents et uniques pour un nettoyage idempotent et la possibilité de reprise. Suivre les ID 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 nom ou par les ID renvoyés, pas par deviner.
12. Valider avant de procéder — ne jamais construire sur un 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 jamais exécuter deux appels use_figma simultanément.
14. Ne jamais halluciner les ID de nœud — toujours lire les ID du registre d'état renvoyé 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 de scripts en ligne de 200 lignes à partir de zéro.
16. Approbation explicite de la phase — à chaque point de contrôle, nommer la prochaine phase explicitement. « semble 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 flux de travail longs)

getPluginData() / setPluginData() ne sont PAS pris en charge dans use_figma. Utiliser getSharedPluginData() / setSharedPluginData() à la place (ceux-ci SONT pris en charge), ou utiliser les recherches basées sur le nom et le registre d'état (ID renvoyés).

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

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

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

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

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

Maintenir 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 : interroger par nom + ID du registre d'état. S'il existe, sauter ou mettre à jour — ne jamais dupliquer.

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

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

« Je continue une construction de système de conception. ID d'exécution : {RUN_ID}. Chargez la compétence figma-generate-library et reprenez depuis la dernière étape terminée. »

5. 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.

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

Réutiliser si tous les éléments suivants 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 jeton est compatible (utilise les mêmes variables ou des variables aliasables)
• Les conventions de nommage correspondent au fichier cible
• Le composant est modifiable (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é différents, mauvais modèle de variante)
• Modèle de jeton incompatible (valeurs codées en dur, schéma de variable différent)
• Problème de propriété (impossible de modifier la bibliothèque)

Envelopper si correspondance visuelle mais incompatibilité d'API :

• Importer le composant de la bibliothèque en tant qu'instance imbriquée à l'intérieur d'un nouveau composant wrapper
• Exposer une API propre sur le wrapper

Priorité trois voies : existant local → importation 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 démarrer à 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 — par exemple, 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 jetons

Motif 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-motifs par phase

Anti-motifs de Phase 0 :

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

Anti-motifs de Phase 1 :

• ❌ Utiliser ALL_SCOPES sur une variable quelconque
• ❌ Dupliquer les valeurs brutes dans la couche sémantique au lieu d'aliaser
• ❌ Ne pas définir la syntaxe du code (casse Dev Mode et aller-retour)
• ❌ Créer des jetons de composants avant de convenir de la taxonomie des jetons

Anti-motifs de Phase 2 :

• ❌ Sauter la page de couverture ou les documents de fondations
• ❌ Mettre plusieurs composants sans rapport sur une page

Anti-motifs de Phase 3 :

• ❌ Créer des composants avant que les fondations n'existent
• ❌ Coder en dur les valeurs de remplissage/trait/espacement/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-motifs généraux :

• ❌ Relancer un script échoué sans comprendre l'erreur d'abord
• ❌ Utiliser la correspondance de préfixe de nom pour le nettoyage (supprime les nœuds de propriété de l'utilisateur)
• ❌ Construire sur un 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équentiel)
• ❌ Deviner/halluciner les ID de nœud de la mémoire (toujours lire depuis le registre d'état)
• ❌ Écrire des scripts en ligne massifs au lieu d'utiliser les scripts d'aide fournis
• ❌ Commencer la Phase 3 parce que l'utilisateur a dit « construire le bouton » sans terminer les Phases 0-2

10. Documents de référence

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

Utiliser votre outil de lecture de fichier pour lire ces documents si nécessaire. Ne pas supposer leur contenu à partir du nom de fichier.

11. Scripts

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