Constructeur de Système de Design — Skill Figma MCP

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

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

Passez toujours skillNames: "figma-generate-library" en appelant use_figma dans le cadre de ce skill. 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 ponctuelle. Construire un système de design nécessite 20–100+ appels use_figma sur plusieurs phases, avec des points de contrôle utilisateur obligatoires entre elles. 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 la plus petite unité utile, validez, obtenez des retours, procédez.

2. Workflow Obligatoire

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

Phase 0 : DISCOVERY (toujours en premier — aucune écriture use_figma)
  0a. Analyser la base de code → extraire 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 des 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 : FOUNDATIONS (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 au 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 les styles de texte (typographie)
  → Critères de sortie : tous les tokens du plan convenu existent, tous les scopes définis, toute la syntaxe de code définie
  ✋ POINT DE CONTRÔLE UTILISATEUR : afficher 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 foundations (nuanciers de couleurs, spécimens typographiques, barres d'espacement)
  → Critères de sortie : toutes les pages prévues existent, la documentation foundations est navigable
  ✋ POINT DE CONTRÔLE UTILISATEUR : afficher la liste des pages + screenshot, attendre l'approbation

Phase 3 : COMPOSANTS (un à la fois — jamais en batch)
  Pour CHAQUE composant (dans l'ordre de dépendance : 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 + mise 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 léger de Code Connect en contexte frais
    → Critères de sortie : nombre de variantes correct, toutes les liaisons vérifiées, screenshot correct
    ✋ POINT DE CONTRÔLE par composant : afficher le screenshot, 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 min, 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 (pas de fill/stroke codés en dur restants)
  4e. Screenshots d'examen final de chaque page
  ✋ POINT DE CONTRÔLE UTILISATEUR : approbation complète

3. Règles Critiques

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

• Utilisez return pour renvoyer les données (auto-sérialisé). NE PAS envelopper dans une IIFE ou appeler closePlugin.
• Retournez 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
• 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 design :

1. Variables AVANT 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 faire correspondre.
3. Une page par composant (par défaut) — exception : familles étroitement liées (ex. Input + helpers) peuvent partager une page avec une séparation claire des sections.
4. Lier les propriétés visuelles aux variables (par défaut) — fill, stroke, padding, radius, gap. Exceptions : géométrie intentionnellement fixe (tailles de grille pixel des icônes, séparateurs statiques).
5. Scopes sur chaque variable — NE JAMAIS laisser en 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 jamais dupliquer les valeurs brutes dans la couche sémantique.
8. Position les variantes après combineAsVariants — elles s'empilent à (0,0). Mise en grille manuelle + redimensionnement.
9. INSTANCE_SWAP pour les icônes — ne jamais créer une variante par icône. Limiter 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 reprise. Suivre les IDs de nœuds 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 IDs retournés, pas en devinant.
12. Valider avant de procéder — 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 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 d'IDs de nœud — toujours lire les IDs du registre d'état retourné par les appels précédents. Ne jamais reconstruire ou deviner un ID de mémoire.
15. Utiliser les scripts helper — 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. "looks good" n'est pas une approbation de passer à la Phase 3 si vous aviez des questions sur la Phase 1.

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

getPluginData() / setPluginData() ne sont PAS supportés dans use_figma. Utilisez getSharedPluginData() / setSharedPluginData() à la place (ils LE SONT), ou utilisez des recherches par nom et le registre d'état (IDs retournés).

Marquer 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 build
node.setSharedPluginData('dsb', 'phase', 'phase3');        // quelle phase l'a créé
node.setSharedPluginData('dsb', 'key', 'component/button');// clé logique unique

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

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

Relire 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é.

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. Si existe, sauter ou mettre à jour — jamais dupliquer.

Protocole de reprise : au démarrage de session ou après troncature de contexte, exécuter un 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.

Prompt de continuation (donner ceci à 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}. Charger le skill figma-generate-library et reprendre depuis la dernière étape complétée."

5. search_design_system — Matrice de Décision de Réutilisation

Chercher 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 ces points sont vrais :

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

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

Envelopper si correspondance visuelle mais API incompatible :

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

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 design nécessitent un jugement humain.

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

7. Conventions de Nommage

Faire correspondre les conventions de fichier existantes. Si commencer à zéro :

Variables (séparées par slash) :

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 — ex. Size=Medium, Style=Primary, State=Default

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

Référence de nommage complète : naming-conventions.md

8. Architecture de 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 Phase 0 :

• ❌ Commencer à créer quelque chose 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-patterns 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 de code (casse le Dev Mode et le round-tripping)
• ❌ Créer des tokens de composants avant d'accepter la taxonomie de tokens

Anti-patterns Phase 2 :

• ❌ Sauter la page de couverture ou la documentation foundations
• ❌ Mettre plusieurs composants non liés sur une page

Anti-patterns Phase 3 :

• ❌ Créer des composants avant que les foundations existent
• ❌ Coder en dur les valeurs de fill/stroke/spacing/radius 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 comprendre l'erreur d'abord
• ❌ Utiliser une correspondance de préfixe de nom pour le nettoyage (supprime les nœuds 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équentiels)
• ❌ Deviner/halluciner des IDs de nœud de mémoire (toujours lire du registre d'état)
• ❌ Écrire des scripts inline massifs au lieu d'utiliser les scripts helper fournis
• ❌ Commencer la Phase 3 parce que l'utilisateur a dit "construire le bouton" sans compléter les Phases 0-2

10. Docs de Référence

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

Utiliser votre outil de lecture de fichier pour lire ces docs si nécessaire. Ne pas supposer leur contenu d'après le nom de fichier.

11. Scripts

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