use_figma — Compétence Figma Plugin API

Utilise use_figma MCP pour exécuter du JavaScript dans les fichiers Figma via l'API Plugin. Toute la documentation détaillée se trouve dans references/.

Passe toujours skillNames: "figma-use" lors de l'appel à use_figma. C'est un paramètre de journalisation utilisé pour suivre l'utilisation des compétences — il n'affecte pas l'exécution.

Si la tâche implique de construire ou mettre à jour une page complète, un écran ou une mise en page multi-section dans Figma à partir du code, charge aussi figma-generate-design. Elle fournit le flux de travail pour découvrir les composants du système de design via search_design_system, les importer et assembler les écrans de manière progressive. Les deux compétences fonctionnent ensemble : celle-ci pour les règles API, l'autre pour le flux de construction d'écrans.

Avant toute chose, charge plugin-api-standalone.index.md pour comprendre ce qui est possible. Quand on te demande d'écrire du code Plugin API, utilise ce contexte pour rechercher dans plugin-api-standalone.d.ts les types, méthodes et propriétés pertinents. C'est la source de vérité définitive pour la surface API. C'est un grand fichier de typages, donc ne le charge pas en entier, utilise la recherche pour les sections pertinentes au besoin.

IMPORTANT : Quand tu travailles avec des systèmes de design, commence par working-with-design-systems/wwds.md pour comprendre les concepts clés, processus et directives pour travailler avec les systèmes de design dans Figma. Charge ensuite les références plus spécifiques pour les composants, variables, styles de texte et styles d'effet au besoin.

1. Règles critiques

1. Utilise return pour renvoyer des données. La valeur retournée est sérialisée en JSON automatiquement (objets, tableaux, chaînes, nombres). NE APPELLE PAS figma.closePlugin() ni n'enverrouille le code dans une IIFE async — c'est géré pour toi.
2. Écris du JavaScript brut avec await et return au niveau supérieur. Le code est automatiquement enveloppé dans un contexte async. N'ENVERROUILLE PAS dans (async () => { ... })().
3. figma.notify() lève "not implemented" — ne l'utilise jamais 3a. getPluginData() / setPluginData() ne sont pas supportés dans use_figma — ne les utilise pas. Utilise plutôt getSharedPluginData() / setSharedPluginData() (ceux-ci SONT supportés), ou suit les ID de nœuds en les retournant et en les passant aux appels suivants.
4. console.log() n'est PAS retourné — utilise return pour la sortie
5. Travaille de manière progressive par petites étapes. Divise les grandes opérations en plusieurs appels use_figma. Valide après chaque étape. C'est la pratique la plus importante pour éviter les bugs.
6. Les couleurs sont dans la plage 0–1 (non 0–255) : {r: 1, g: 0, b: 0} = rouge
7. Les remplissages/traits sont des tableaux en lecture seule — clone, modifie, réassigne
8. La police DOIT être chargée avant toute opération sur du texte : await figma.loadFontAsync({family, style})
9. Les pages se chargent progressivement — utilise await figma.setCurrentPageAsync(page) pour basculer vers une page et charger son contenu (voir Règles de page ci-dessous)
10. setBoundVariableForPaint retourne une NOUVELLE peinture — doit être capturée et réassignée
11. createVariable accepte la collection comme objet ou chaîne ID (objet préféré)
12. layoutSizingHorizontal/Vertical = 'FILL' DOIT être défini APRÈS parent.appendChild(child) — définir avant append lève une erreur. Même pour 'HUG' sur les nœuds non-auto-layout.
13. Positionne les nouveaux nœuds de niveau supérieur loin de (0,0). Les nœuds ajoutés directement à la page par défaut à (0,0). Scanne figma.currentPage.children pour trouver une position libre (ex. à droite du nœud le plus à droite). Ceci s'applique seulement aux nœuds au niveau de la page — les nœuds imbriqués dans d'autres cadres ou conteneurs auto-layout sont positionnés par leur parent. Voir Gotchas.
14. En cas d'erreur use_figma, ARRÊTE. N'essaie PAS de réessayer immédiatement. Les scripts échoués sont atomiques — si un script errore, il n'est pas exécuté du tout et aucun changement n'est apporté au fichier. Lis le message d'erreur attentivement, corrige le script, puis réessaie. Voir Error Recovery.
15. DOIT retourner TOUS les ID de nœuds créés/modifiés. Quand un script crée de nouveaux nœuds ou en modifie des existants sur le canevas, recueille chaque ID de nœud affecté et les retourne dans un objet structuré (ex. return { createdNodeIds: [...], mutatedNodeIds: [...] }). C'est essentiel pour que les appels suivants les référencent, les valident ou les nettoient.
16. Définis toujours variable.scopes explicitement lors de la création de variables. La valeur par défaut ALL_SCOPES pollue chaque sélecteur de propriété — rarement ce que tu veux. Utilise des portées spécifiques comme ["FRAME_FILL", "SHAPE_FILL"] pour les arrière-plans, ["TEXT_FILL"] pour les couleurs de texte, ["GAP"] pour l'espacement, etc. Voir variable-patterns.md pour la liste complète.
17. await chaque Promise. Ne laisse jamais une Promise sans attendre — les appels async non attendus (ex. figma.loadFontAsync(...) sans await, ou figma.setCurrentPageAsync(page) sans await) s'exécuteront en arrière-plan, causant des défaillances silencieuses ou des conditions de concurrence. Le script peut retourner avant que l'opération async se termine, causant des données manquantes ou des changements partiels.

Pour des exemples détaillés MAUVAIS/CORRECT de chaque règle, voir Gotchas & Common Mistakes.

2. Règles de page (Critiques)

Le contexte de page se réinitialise entre les appels use_figma — figma.currentPage démarre à la première page à chaque fois.

Basculer entre les pages

Utilise await figma.setCurrentPageAsync(page) pour basculer vers une page et charger son contenu. Le setter synchrone figma.currentPage = page lève une erreur dans les environnements use_figma.

// Bascule vers une page spécifique (charge son contenu)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children est maintenant rempli

// Itère sur toutes les pages
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // page.children est maintenant chargé — lis ou modifie ici
}

Entre les exécutions de script

figma.currentPage se réinitialise à la première page au début de chaque appel use_figma. Si ton flux de travail s'étend sur plusieurs appels et cible une page non-défaut, appelle await figma.setCurrentPageAsync(page) au début de chaque invocation.

Tu peux appeler use_figma plusieurs fois pour construire progressivement sur l'état du fichier, ou pour récupérer des informations avant d'écrire un autre script. Par exemple, écris un script pour obtenir les métadonnées des nœuds existants, return ces données, puis utilise-les dans un script suivant pour modifier ces nœuds.

3. return est ton canal de sortie

L'agent ne voit QUE la valeur que tu return. Tout le reste est invisible.

• Retourner des IDs (CRITIQUE) : Chaque script qui crée ou modifie des nœuds du canevas DOIT retourner tous les ID affectés — ex. return { createdNodeIds: [...], mutatedNodeIds: [...] }. C'est une exigence stricte, pas optionnelle.
• Signalisation de progression : return { createdNodeIds: [...], count: 5, errors: [] }
• Info d'erreur : Les erreurs levées sont capturées et retournées automatiquement — laisse-les simplement se propager ou lève-les explicitement.
• La sortie console.log() n'est jamais retournée à l'agent
• Retourne toujours des données exploitables (IDs, comptes, statut) afin que les appels suivants puissent référencer les objets créés

4. Mode éditeur

use_figma fonctionne en mode design (editorType "figma", le défaut). FigJam ("figjam") a un ensemble différent de types de nœuds disponibles — la plupart des nœuds de design y sont bloqués.

Disponibles en mode design : Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.

Bloqués en mode design : Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, Webpage.

5. Flux de travail progressif (Comment éviter les bugs)

La cause la plus courante de bugs est d'essayer de faire trop en un seul appel use_figma. Travaille par petites étapes et valide après chacune.

Le modèle

1. Inspecte d'abord. Avant de créer quoi que ce soit, lance une use_figma en lecture seule pour découvrir ce qui existe déjà dans le fichier — pages, composants, variables, conventions de nommage. Fais correspondre ce qui y est.
2. Fais une chose par appel. Crée les variables dans un appel, les composants dans le suivant, compose les mises en page dans un autre. N'essaie pas de construire un écran entier dans un seul script.
3. Retourne les IDs de chaque appel. Retourne toujours les IDs des nœuds créés, IDs de variables, IDs de collection dans des objets structurés (ex. return { createdNodeIds: [...] }). Tu en auras besoin comme entrées des appels suivants.
4. Valide après chaque étape. Utilise get_metadata pour vérifier la structure (comptes, noms, hiérarchie, positions). Utilise get_screenshot après les jalons majeurs pour détecter les problèmes visuels.
5. Corrige avant de continuer. Si la validation révèle un problème, corrige-le avant de procéder à l'étape suivante. Ne construis pas sur une base cassée.

Ordre d'étapes suggéré pour les tâches complexes

Étape 1 : Inspecte le fichier — découvre les pages, composants, variables, conventions existants
Étape 2 : Crée les tokens/variables (si nécessaire)
       → valide avec get_metadata
Étape 3 : Crée les composants individuels
       → valide avec get_metadata + get_screenshot
Étape 4 : Compose les mises en page à partir des instances de composants
       → valide avec get_screenshot
Étape 5 : Vérification finale

Ce qu'il faut valider à chaque étape

6. Récupération d'erreur et auto-correction

use_figma est atomique — les scripts échoués ne s'exécutent pas. Si un script errore, aucun changement n'est apporté au fichier. Le fichier reste dans le même état qu'avant l'appel. Cela signifie qu'il n'y a pas de nœuds partiels, pas d'éléments orphelins du script échoué, et le réessai après une correction est sûr.

Quand use_figma retourne une erreur

1. ARRÊTE. Ne corrige pas immédiatement le code et ne réessaie pas.
2. Lis le message d'erreur attentivement. Comprends exactement ce qui s'est mal passé — mauvaise utilisation API, police manquante, valeur de propriété invalide, etc.
3. Si l'erreur n'est pas claire, appelle get_metadata ou get_screenshot pour comprendre l'état actuel du fichier.
4. Corrige le script en fonction du message d'erreur.
5. Réessaie le script corrigé.

Modèles courants d'auto-correction

Quand le script réussit mais le résultat semble faux

1. Appelle get_metadata pour vérifier la correction structurelle (hiérarchie, comptes, positions).
2. Appelle get_screenshot pour vérifier la correction visuelle. Cherche bien les textes coupés/clippés (hauteurs de ligne coupant le contenu) et les chevauchements d'éléments — ce sont des phénomènes courants et faciles à manquer.
3. Identifie la discordance — est-ce structurel (hiérarchie fausse, nœuds manquants) ou visuel (couleurs mauvaises, mise en page cassée, contenu clippé) ?
4. Écris un script de correction ciblé qui modifie seulement les parties cassées — ne recréé pas tout.

Pour le flux de travail de validation complet, voir Validation & Error Recovery.

7. Checklist de pré-lancement

Avant de soumettre UN SEUL appel use_figma, vérifie :

• [ ] Le code utilise return pour renvoyer les données (PAS figma.closePlugin())
• [ ] Le code n'est PAS enveloppé dans une IIFE async (auto-enveloppé pour toi)
• [ ] La valeur return inclut des données structurées avec infos exploitables (IDs, comptes)
• [ ] AUCUNE utilisation de figma.notify() n'importe où
• [ ] AUCUNE utilisation de console.log() comme sortie (utilise return à la place)
• [ ] Toutes les couleurs utilisent la plage 0–1 (non 0–255)
• [ ] Les remplissages/traits sont réassignés comme nouveaux tableaux (non mutés sur place)
• [ ] Les changements de page utilisent await figma.setCurrentPageAsync(page) (le setter synchrone lève)
• [ ] layoutSizingVertical/Horizontal = 'FILL' est défini APRÈS parent.appendChild(child)
• [ ] loadFontAsync() appelé AVANT tout changement de propriété de texte
• [ ] lineHeight/letterSpacing utilisent le format {unit, value} (pas des nombres nus)
• [ ] resize() est appelé AVANT de définir les modes de dimensionnement (resize les réinitialise à FIXED)
• [ ] Pour les flux de travail multi-étapes : les IDs des appels précédents sont passés comme littéraux de chaîne (pas de variables)
• [ ] Les nouveaux nœuds de niveau supérieur sont positionnés loin de (0,0) pour éviter de chevaucher le contenu existant
• [ ] TOUS les IDs de nœuds créés/modifiés sont recueillis et inclus dans la valeur return
• [ ] Chaque appel async (loadFontAsync, setCurrentPageAsync, importComponentByKeyAsync, etc.) est awaité — pas de Promises feu-et-oubli

8. Découvre les conventions avant de créer

Inspecte toujours le fichier Figma avant de créer quoi que ce soit. Les différents fichiers utilisent différentes conventions de nommage, structures de variables et modèles de composants. Ton code doit correspondre à ce qui y existe déjà, non imposer de nouvelles conventions.

En cas de doute sur une convention (nommage, portée, structure), vérifie d'abord le fichier Figma, puis la base de code de l'utilisateur. Reviens seulement aux modèles courants quand ni l'un ni l'autre n'existe.

Scripts d'inspection rapide

Liste toutes les pages et nœuds de niveau supérieur :

const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
return pages.join('\n');

Liste les composants existants sur toutes les pages :

const results = [];
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  page.findAll(n => {
    if (n.type === 'COMPONENT' || n.type === 'COMPONENT_SET')
      results.push(`[${page.name}] ${n.name} (${n.type}) id=${n.id}`);
    return false;
  });
}
return results.join('\n');

Liste les collections de variables existantes et leurs conventions :

const collections = await figma.variables.getLocalVariableCollectionsAsync();
const results = collections.map(c => ({
  name: c.name, id: c.id,
  varCount: c.variableIds.length,
  modes: c.modes.map(m => m.name)
}));
return results;

9. Docs de référence

Charge-les au besoin en fonction de ce que ta tâche implique :

10. Exemples de snippets

Tu verras des snippets tout au long de la documentation. Ces snippets contiennent du code Plugin API utile qui peut être réutilisé. Utilise-les tels quels, ou comme code de démarrage au fur et à mesure. S'il y a des concepts clés qui sont mieux documentés comme snippets génériques, mets-les en évidence et écris sur disque afin de pouvoir les réutiliser à l'avenir.