use_figma. Compétence API Plugin Figma
Utilisez l'outil use_figma 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/.
Passez toujours skillNames: "figma-use" lors de l'appel à use_figma. Il s'agit d'un paramètre de journalisation permettant de suivre l'utilisation de la compétence. Cela n'affecte pas l'exécution.
Si les outils Figma MCP apparaissent comme des outils différés, chargez tous leurs schémas en un seul appel ToolSearch en utilisant la syntaxe select:, par ex. ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file". Un aller-retour vaut mieux que six.
Si la tâche consiste à construire ou mettre à jour une page, un écran ou une disposition multi-section complète dans Figma à partir du code, chargez également figma-generate-design. Il fournit le workflow pour découvrir les composants du système de design via search_design_system, les importer et assembler les écrans de manière incrémentielle. Les deux compétences fonctionnent ensemble : celle-ci pour les règles de l'API, celle-là pour le workflow de construction d'écran.
Si la tâche consiste à créer ou construire un composant dans Figma (même un seul composant), chargez également figma-generate-library. Il fournit le workflow de création de composants, les fondations des variables, les ensembles de variants, les liaisons de tokens de design. Ce que figma-use seul ne couvre pas.
Avant toute chose, chargez plugin-api-standalone.index.md pour comprendre ce qui est possible. Lorsqu'on vous demande d'écrire du code d'API Plugin, utilisez ce contexte pour grep plugin-api-standalone.d.ts pour les types, méthodes et propriétés pertinents. C'est la source de vérité définitive pour la surface de l'API. Il s'agit d'un gros fichier de typage, ne le chargez pas en une seule fois, cherchez les sections pertinentes au besoin.
IMPORTANT : lorsque vous travaillez avec des systèmes de design, commencez par working-with-design-systems/wwds.md pour comprendre les concepts clés, les processus et les directives pour travailler avec les systèmes de design 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
- Utilisez
returnpour renvoyer des données. La valeur de retour est automatiquement sérialisée en JSON (objets, tableaux, chaînes, nombres). N'appelez PASfigma.closePlugin()et n'enveloppez pas le code dans un IIFE asynchrone. Ceci est géré pour vous. - Écrivez du JavaScript simple avec
awaitetreturnau niveau racine. Le code est automatiquement enveloppé dans un contexte asynchrone. N'enveloppez pas dans(async () => { ... })(). figma.notify()lève "not implemented" : ne l'utilisez jamais. 3a.getPluginData()/setPluginData()ne sont pas pris en charge dansuse_figma: ne les utilisez pas. Utilisez plutôtgetSharedPluginData()/setSharedPluginData()(ceux-ci sont pris en charge), ou suivez les ID de nœuds en les renvoyant et en les passant aux appels suivants.console.log()n'est PAS renvoyé. Utilisezreturnpour la sortie.- Travaillez par étapes incrémentielles et petites. Divisez les grosses opérations en plusieurs appels
use_figma. Validez après chaque étape. C'est la pratique la plus importante pour éviter les bugs. - Les couleurs sont dans la plage 0-1 (pas 0-255) :
{r: 1, g: 0, b: 0}= rouge. - Les remplissages/traits sont des tableaux en lecture seule : clonez, modifiez, réaffectez.
- Chaque édition de texte suit la recette canonique : charger la police →
await→ muter → renvoyer les IDs des nœuds affectés. Ignorer le chargement lèveCannot write to node with unloaded font "<famille> <style>". La règle couvre plus quecharacters: elle s'applique à toute opération sur des nœuds avec des polices non chargées (appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode, les callbacksfindAlltouchant du texte). Lors de la mutation de texte existant, chargez les polices actuelles du nœud viagetStyledTextSegments(['fontName']), pas une valeur par défaut codée en dur. Inter est préchargé dans la plupart des environnements, donc d'autres familles déclenchent ce bug plus souvent. La recette est la même pour chaque police. Utilisez d'abordawait figma.listAvailableFontsAsync()si la chaîne de style n'est pas vérifiée. Voir Recette canonique d'édition de texte. - Les pages se chargent de manière incrémentielle : utilisez
await figma.setCurrentPageAsync(page)pour changer de page et charger leur contenu. Le setter synchronefigma.currentPage = pagene fonctionne PAS et lèvera une erreur (voir Règles de page ci-dessous). setBoundVariableForPaintrenvoie un NOUVEAU paint, vous devez le capturer et le réaffecter.createVariableaccepte la collection sous forme d'objet ou de chaîne ID (l'objet est préféré).layoutSizingHorizontal/Verticalest restreint en valeur par le contexte structurel,FIXEDfonctionne toujours,HUGetFILLne fonctionnent pas.'HUG'n'est valide que sur un cadre auto-layout lui-même OU sur un enfant TEXTE de celui-ci.'FILL'n'est valide que sur un enfant d'un cadre auto-layout qui n'est pas en position absolue, pas à l'intérieur d'un cadre immuable, et pas un enfant de grille de canvas. Conséquence pratique : rattachez d'abord à un parent auto-layout, puis définissezHUG/FILL: un nœud nouvellement créé ou non rattaché ne peut pas encore satisfaire la règle. La propriété elle-même existe sur chaqueSceneNode; l'erreur est un rejet de valeur, pas "aucune propriété de ce type". Voir Pièges. 12a. Utilisez l'auto-layout pour les conteneurs qui contiennent des enfants liés. Lorsque les enfants ont une relation structurelle, empilés, côte à côte, alignés, espacés, enveloppés, enveloppez-les dansfigma.createAutoLayout(), pasfigma.createFrame()avec desx/yabsolus. Les coordonnées absolues gouvernent l'emplacement d'un conteneur sur le canvas ; l'auto-layout gouverne comment ses enfants se rapportent à l'intérieur. Ignorer le conteneur ne laisse aucune protection contre le reflow de texte, les changements de contenu ou les chevauchements.- Positionnez les nouveaux nœuds de premier niveau loin de (0,0). Les nœuds ajoutés directement à la page sont par défaut à (0,0). Parcourez
figma.currentPage.childrenpour trouver une position libre (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 auto-layout sont positionnés par leur parent. Voir Pièges. - En cas d'erreur
use_figma, ARRÊTEZ-VOUS. Ne réessayez PAS immédiatement. Les scripts échoués sont atomiques : si un script échoue, il n'est pas exécuté du tout et aucune modification n'est apportée au fichier. Lisez attentivement le message d'erreur, corrigez le script, puis réessayez. Voir Récupération d'erreur. - Vous DEVEZ
returnTOUS les IDs de nœuds créés/mutés. Chaque fois qu'un script crée de nouveaux nœuds ou mute des nœuds existants sur le canvas, collectez chaque ID de nœud affecté et renvoyez-les dans un objet structuré (par ex.return { createdNodeIds: [...], mutatedNodeIds: [...] }). Ceci est essentiel pour que les appels ultérieurs puissent référencer, valider ou nettoyer ces nœuds. - Définissez toujours
variable.scopesexplicitement lors de la création de variables. La valeur par défautALL_SCOPESpollue tous les sélecteurs de propriétés, ce n'est presque jamais ce que vous voulez. Utilisez des scopes 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. awaitchaque Promise. Ne laissez jamais une Promise non attendue, les appels async non attendus (par exemple,figma.loadFontAsync(...)sansawait, oufigma.setCurrentPageAsync(page)sansawait) seront oubliés, provoquant des échecs silencieux ou des conditions de course. Le script peut se terminer avant que l'opération async ne soit terminée, conduisant à des données manquantes ou à des modifications à moitié appliquées.
Pour des exemples détaillés FAUX/CORRECT de chaque règle, voir Pièges et erreurs courantes.
2. Règles de page (Critiques)
Le contexte de page se réinitialise entre les appels use_figma : figma.currentPage commence sur la première page à chaque fois.
Changer de page
Utilisez await figma.setCurrentPageAsync(page) pour changer de page et charger leur contenu. Le setter synchrone figma.currentPage = page ne fonctionne PAS : il lève "Setting figma.currentPage is not supported" dans use_figma. Utilisez toujours la méthode asynchrone.
// Passer à une page spécifique (charge son contenu)
const targetPage = figma.root.children.find((p) => p.name === "Ma Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children est maintenant peuplé
Appelez setCurrentPageAsync au plus une fois par invocation de use_figma, répartissez le travail multi-page en parallèle
Un script ne doit changer de page qu'une seule fois. Ne bouclez jamais sur figma.root.children et ne changez pas de page à l'intérieur de la boucle.
Si le travail couvre plusieurs pages, divisez-le en N appels use_figma (un par page cible) et émettez-les en parallèle : un seul message assistant contenant N blocs d'utilisation d'outil use_figma. Le moteur les exécute en parallèle ; chaque script définit currentPage exactement une fois.
Instruction explicite : lors de la répartition, vous DEVEZ émettre les N appels d'outil dans un seul message. Ne les envoyez pas sur plusieurs tours. N'attendez pas l'un avant d'émettre le suivant. Les appels séquentiels par page sont plus lents que le motif en boucle que cette règle remplace et gaspillent tout l'avantage de la division.
// À ÉVITER, change de page N fois dans un seul script, recharge le fichier à chaque fois
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... toucher cette page ...
}
// PRÉFÉRER, appel de découverte en lecture seule pour obtenir les IDs de page, puis dans le MESSAGE SUIVANT
// émettre N appels d'outil use_figma en parallèle (un par page), chacun définissant currentPage une fois.
Par défaut, répartissez en parallèle pour tout travail multi-page, lectures et écritures. Voir gotchas.md → Définir la page courante une fois par appel use_figma pour la justification complète.
Entre les exécutions de script
figma.currentPage est réinitialisé à la première page au début de chaque appel use_figma. Si votre workflow s'étend sur plusieurs appels et cible une page non par 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 des informations avant d'écrire un autre script. Par exemple, écrivez un script pour obtenir des métadonnées sur les nœuds existants, return ces données, puis utilisez-les dans un script subséquent 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.
- Retourner des IDs (CRITIQUE) : Chaque script qui crée ou mute des nœuds du canvas DOIT renvoyer tous les IDs de nœuds affectés, par ex.
return { createdNodeIds: [...], mutatedNodeIds: [...] }. C'est une exigence stricte, pas facultative. - 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
throwexplicitement. - La sortie de
console.log()n'est jamais renvoyée à l'agent. - Renvoyez toujours des données exploitables (IDs, comptages, statut) pour que les appels ultérieurs puissent référencer les objets créés.
4. Mode Éditeur
use_figma fonctionne en mode design (editorType "figma", par défaut). FigJam ("figjam") et Slides ("slides") ont des ensembles différents de types de nœuds disponibles. La plupart des nœuds de design sont bloqués dans FigJam, et les nœuds propres à FigJam sont bloqués dans Slides.
Identifiez l'éditeur à partir de l'URL : Design = figma.com/design/..., FigJam = figma.com/board/..., Slides = figma.com/slides/.... Confirmez avant de supposer qu'une API est disponible.
Disponible en mode design : Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.
Bloqué en mode design : Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, SlideGrid, InteractiveSlideElement, Webpage.
Disponible en mode Slides : Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Section, TextPath, Slide, SlideRow, SlideGrid, InteractiveSlideElement.
Bloqué en mode Slides : Sticky, Connector, ShapeWithText, CodeBlock, Webpage, Page.
APIs propres au design (pas seulement les types de nœuds) : figma.createPage() est disponible uniquement dans les fichiers Design (figma.com/design/...). Dans FigJam (figma.com/board/...) et Slides (figma.com/slides/...), il lève TypeError: figma.createPage no such property 'createPage' on the figma global object. N'émettez pas figma.createPage() dans les workflows FigJam ou Slides.
Note Slides : Il n'existe pas encore d'outil de lecture dédié pour les fichiers Slides. Utilisez
use_figmaavec des scripts en lecture seule pour l'inspection (voir Section 6 motif "Inspecter d'abord"), etget_screenshot/await node.screenshot()pour le contexte visuel. Pour les conseils spécifiques à l'API Slides, chargez la compétence figma-use-slides.
5. APIs Efficaces. Préférez-les aux alternatives verbeuses
Ces APIs réduisent le code passe-partout, éliminent les erreurs d'ordonnancement et compressent la sortie en tokens. Préférez-les toujours aux alternatives verbeuses.
node.query(selector) : Recherche de nœuds de type CSS
Trouvez des nœuds dans un sous-arbre en utilisant des sélecteurs de type CSS. Remplace les boucles verbeuses findAll + filtre.
// AVANT, parcours verbeux
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')
// APRÈS, en une ligne avec query
const texts = frame.query('TEXT[name=Title]')
Syntaxe du sélecteur :
- Type :
FRAME,TEXT,RECTANGLE,ELLIPSE,COMPONENT,INSTANCE,SECTION(insensible à la casse) - Attribut exact :
[name=Card],[visible=true],[opacity=0.5] - Attribut sous-chaîne :
[name*=art](contient),[name^=Header](commence par),[name$=Nav](termine par) - Parcours par chemin pointé :
[fills.0.type=SOLID],[fills.*.type=SOLID](index générique) - Correspondance d'instance :
[mainComponent=nodeId],[mainComponent.name=Button] - Combinateurs :
FRAME > TEXT(enfant direct),FRAME TEXT(tout descendant),A + B(frère adjacent),A ~ B(frère général) - Pseudo-classes :
:first-child,:last-child,:nth-child(2),:not(TYPE),:is(FRAME, RECTANGLE),:where(TEXT, ELLIPSE) - ID de nœud :
#nodeIdou GUID nu - Virgule :
TEXT, RECTANG