use_figma — Compétence API Plugin Figma

Utilisez use_figma MCP pour exécuter du JavaScript dans les fichiers Figma via l'API Plugin. Tous les documents de référence détaillés se trouvent dans references/.

Transmettez 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 de mettre à jour une page complète, un écran ou une disposition multi-section dans Figma à partir du code, chargez aussi figma-generate-design. Cela fournit le flux de travail pour découvrir les composants du système de conception via search_design_system, les importer et assembler les écrans progressivement. Les deux compétences fonctionnent ensemble : celle-ci pour les règles de l'API, celle-là pour le flux de travail de construction d'écran.

Avant toute chose, chargez plugin-api-standalone.index.md pour comprendre ce qui est possible. Quand on vous demande d'écrire du code API plugin, utilisez ce contexte pour chercher dans plugin-api-standalone.d.ts les types, méthodes et propriétés pertinents. C'est la source définitive de vérité pour la surface de l'API. C'est un grand fichier de typings, ne le chargez pas en entier, cherchez les sections pertinentes au fur et à mesure.

IMPORTANT : Chaque fois que vous travaillez avec des systèmes de conception, commencez par working-with-design-systems/wwds.md pour comprendre les concepts clés, processus et directives pour travailler avec les systèmes de conception dans Figma. Chargez ensuite les références plus spécifiques pour les composants, les variables, les styles de texte et les styles d'effet selon les besoins.

1. Règles Critiques

1. Utilisez return pour renvoyer les données. La valeur de retour est automatiquement sérialisée en JSON (objets, tableaux, chaînes, nombres). Ne appelez PAS figma.closePlugin() ni n'enveloppez le code dans une async IIFE — ceci est géré pour vous.
2. Écrivez du JavaScript ordinaire avec await et return au niveau supérieur. Le code est automatiquement enveloppé dans un contexte async. N'enveloppez PAS dans (async () => { ... })().
3. figma.notify() lève « not implemented » — ne l'utilisez jamais 3a. getPluginData() / setPluginData() ne sont pas supportés dans use_figma — ne les utilisez pas. Utilisez getSharedPluginData() / setSharedPluginData() à la place (ceux-ci SONT supportés), ou suivez les IDs de nœud en les renvoyant et en les passant aux appels suivants.
4. console.log() ne sera PAS renvoyé — utilisez return pour la sortie
5. Travaillez progressivement en petites étapes. Divisez les grandes opérations en plusieurs appels use_figma. Validez après chaque étape. C'est la pratique la plus importante pour éviter les bugs.
6. Les couleurs sont dans la plage 0–1 (pas 0–255) : {r: 1, g: 0, b: 0} = rouge
7. Les remplissages/traits sont des tableaux en lecture seule — clonez, modifiez, réattribuez
8. La police DOIT être chargée avant toute opération de texte : await figma.loadFontAsync({family, style})
9. Les pages se chargent progressivement — utilisez await figma.setCurrentPageAsync(page) pour basculer les pages et charger leur contenu (voir Page Rules ci-dessous)
10. setBoundVariableForPaint renvoie une NOUVELLE peinture — doit être capturée et réattribuée
11. createVariable accepte la collection objet ou chaîne d'ID (objet préféré)
12. layoutSizingHorizontal/Vertical = 'FILL' DOIT être défini APRÈS parent.appendChild(child) — définir avant l'ajout lève une erreur. La même chose s'applique à 'HUG' sur les nœuds non-auto-layout.
13. Positionnez 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). Scannez figma.currentPage.children pour trouver une position claire (par exemple, à droite du nœud le plus à droite). Cela s'applique uniquement aux nœuds de niveau page — les nœuds imbriqués dans d'autres cadres ou conteneurs d'auto-layout sont positionnés par leur parent. Voir Gotchas.
14. En cas d'erreur use_figma, ARRÊTEZ. NE réessayez PAS immédiatement. Les scripts échoués sont atomiques — si un script génère une erreur, il n'est pas exécuté du tout et aucun changement n'est apporté au fichier. Lisez le message d'erreur attentivement, corrigez le script, puis réessayez. Voir Error Recovery.
15. DOIT return TOUS les IDs de nœud créés/mutés. Chaque fois qu'un script crée de nouveaux nœuds ou en mute des existants sur le canevas, collectez tous les IDs de nœud affectés et renvoyez-les dans un objet structuré (par exemple return { createdNodeIds: [...], mutatedNodeIds: [...] }). C'est essentiel pour que les appels suivants puissent référencer, valider ou nettoyer ces nœuds.
16. Toujours définir variable.scopes explicitement lors de la création de variables. Le paramètre par défaut ALL_SCOPES pollue chaque sélecteur de propriété — presque jamais ce que vous voulez. Utilisez 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 laissez jamais une Promise non-attendue — les appels async non-attendus (par exemple figma.loadFontAsync(...) sans await, ou figma.setCurrentPageAsync(page) sans await) se déclencheront et oublieront, causant des défaillances silencieuses ou des conditions de course. Le script peut revenir avant que l'opération async se termine, entraînant des données manquantes ou des changements partiellement appliqués.

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

2. Page Rules (Critique)

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

Basculer les pages

Utilisez await figma.setCurrentPageAsync(page) pour basculer les pages et charger leur contenu. Le seteur synchrone figma.currentPage = page lève une erreur dans les runtimes use_figma.

// Basculer 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 peuplé

// Itérer sur toutes les pages
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // page.children est maintenant chargé — lisez ou modifiez-les ici
}

Entre les exécutions de scripts

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

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

3. return Est Votre Canal de Sortie

L'agent voit UNIQUEMENT la valeur que vous return. Tout le reste est invisible.

• Renvoi des IDs (CRITIQUE) : Chaque script qui crée ou mute des nœuds de canevas DOIT renvoyer tous les IDs de nœud affectés — par exemple return { createdNodeIds: [...], mutatedNodeIds: [...] }. C'est une exigence obligatoire, pas optionnelle.
• Rapport de progression : return { createdNodeIds: [...], count: 5, errors: [] }
• Info d'erreur : Les erreurs levées sont automatiquement capturées et renvoyées — laissez-les simplement se propager ou throw explicitement.
• La sortie console.log() n'est jamais renvoyée à l'agent
• Toujours renvoyer des données actionnables (IDs, comptages, statut) pour que les appels suivants puissent référencer les objets créés

4. Mode Éditeur

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

Disponible en mode de conception : Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.

Bloqué en mode de conception : 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 dans un seul appel use_figma. Travaillez en petites étapes et validez après chacune.

Le modèle

1. Inspectez d'abord. Avant de créer quoi que ce soit, exécutez un use_figma en lecture seule pour découvrir ce qui existe déjà dans le fichier — pages, composants, variables, conventions de nommage. Correspondez à ce qui s'y trouve.
2. Faites une chose par appel. Créez des variables dans un appel, créez des composants dans le suivant, composez des mises en page dans un autre. N'essayez pas de construire un écran entier dans un script.
3. Renvoyez les IDs de chaque appel. Toujours return les IDs de nœud créés, les IDs de variable, les IDs de collection comme des objets (par exemple return { createdNodeIds: [...] }). Vous en aurez besoin comme entrées pour les appels suivants.
4. Validez après chaque étape. Utilisez get_metadata pour vérifier la structure (comptages, noms, hiérarchie, positions). Utilisez get_screenshot après les jalons majeurs pour détecter les problèmes visuels.
5. Corrigez avant de continuer. Si la validation révèle un problème, corrigez-le avant de passer à l'étape suivante. Ne construisez pas sur une base cassée.

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

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

Ce qu'il faut valider à chaque étape

6. Récupération d'Erreur & Auto-Correction

use_figma est atomique — les scripts échoués ne s'exécutent pas. Si un script génère une erreur, 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 réessayer après une correction est sûr.

Quand use_figma renvoie une erreur

1. ARRÊTEZ. Ne corrigez pas immédiatement le code et ne réessayez pas.
2. Lisez le message d'erreur attentivement. Comprenez exactement ce qui s'est mal passé — utilisation incorrecte de l'API, police manquante, valeur de propriété invalide, etc.
3. Si l'erreur n'est pas claire, appelez get_metadata ou get_screenshot pour comprendre l'état actuel du fichier.
4. Corrigez le script en fonction du message d'erreur.
5. Réessayez le script corrigé.

Modèles d'auto-correction courants

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

1. Appelez get_metadata pour vérifier la correction structurelle (hiérarchie, comptages, positions).
2. Appelez get_screenshot pour vérifier la correction visuelle. Regardez attentivement le texte recadré/coupé (hauteurs de ligne coupant le contenu) et les éléments qui se chevauchent — ceux-ci sont courants et faciles à manquer.
3. Identifiez la discordance — est-elle structurelle (hiérarchie fausse, nœuds manquants) ou visuelle (couleurs fausses, mise en page cassée, contenu coupé) ?
4. Écrivez un script de correction ciblé qui modifie uniquement les parties cassées — ne recréez pas tout.

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

7. Checklist Pré-Vol

Avant de soumettre UN appel use_figma, vérifiez :

• [ ] Le code utilise return pour envoyer les données (PAS figma.closePlugin())
• [ ] Le code n'est PAS enveloppé dans une async IIFE (enveloppé automatiquement pour vous)
• [ ] La valeur return inclut des données structurées avec info actionnables (IDs, comptages)
• [ ] AUCUNE utilisation de figma.notify() nulle part
• [ ] AUCUNE utilisation de console.log() comme sortie (utilisez return à la place)
• [ ] Toutes les couleurs utilisent la plage 0–1 (pas 0–255)
• [ ] Les remplissages/traits sont réattribués comme nouveaux tableaux (pas 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 de nombres nus)
• [ ] resize() est appelé AVANT la définition des 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 variables)
• [ ] Les nouveaux nœuds de niveau supérieur sont positionnés loin de (0,0) pour éviter le chevauchement avec le contenu existant
• [ ] TOUS les IDs de nœud créés/mutés sont collectés et inclus dans la valeur return
• [ ] Chaque appel async (loadFontAsync, setCurrentPageAsync, importComponentByKeyAsync, etc.) est awaité — pas de Promises oubliées

8. Découvrir les Conventions Avant de Créer

Toujours inspecter le fichier Figma avant de créer quelque chose. Les différents fichiers utilisent différentes conventions de nommage, structures de variables et modèles de composants. Votre code devrait correspondre à ce qui est déjà là, pas imposer de nouvelles conventions.

Quand vous doutez d'une convention (nommage, portée, structure), vérifiez d'abord le fichier Figma, puis la base de code de l'utilisateur. Retombez sur les modèles communs uniquement quand aucun des deux n'existe.

Scripts d'inspection rapide

Lister 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');

Lister 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');

Lister 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

Chargez-les selon les besoins en fonction de ce que votre tâche implique :

10. Exemples de Snippet

Vous verrez des snippets tout au long de la documentation ici. Ces snippets contiennent du code API plugin utile qui peut être réutilisé. Utilisez-les tels quels, ou comme code de démarrage au fur et à mesure. Si des concepts clés sont mieux documentés comme des snippets génériques, appelez-les et écrivez sur disque pour pouvoir réutiliser à l'avenir.