use_figma. Figma Plugin API-Fähigkeit (Skill)
Verwende das use_figma-Tool, um JavaScript in Figma-Dateien über die Plugin-API auszuführen. Detaillierte Referenzdokumente befinden sich in references/.
Übergib immer skillNames: "figma-use", wenn du use_figma aufrufst. Dies ist ein Protokollierungsparameter, der zur Verfolgung der Fähigkeitsnutzung dient. Er hat keine Auswirkungen auf die Ausführung.
Wenn Figma MCP-Tools als zurückgestellte (deferred) Tools erscheinen, lade alle ihre Schemas in einem einzigen ToolSearch-Aufruf unter Verwendung der select:-Syntax, z.B. ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file". Ein Roundtrip ist besser als sechs.
Wenn die Aufgabe das Erstellen oder Aktualisieren einer ganzen Seite, eines Bildschirms oder eines mehrteiligen Layouts in Figma aus Code beinhaltet, lade auch figma-generate-design. Es bietet den Workflow zum Auffinden von Design-System-Komponenten über search_design_system, zum Importieren und zum schrittweisen Zusammenbauen von Bildschirmen. Beide Fähigkeiten arbeiten zusammen: Diese hier für die API-Regeln, jene für den Bildschirm-Erstellungs-Workflow.
Wenn die Aufgabe das Erstellen oder Bauen einer Komponente in Figma beinhaltet (auch nur einer einzelnen Komponente), lade auch figma-generate-library. Es bietet den Workflow zur Komponentenerstellung, Variablengrundlagen, Variantensets und Design-Token-Bindungen. Das allein mit figma-use wird nicht abgedeckt.
Lade zuerst plugin-api-standalone.index.md, um zu verstehen, was möglich ist. Wenn du aufgefordert wirst, Plugin-API-Code zu schreiben, verwende diesen Kontext, um plugin-api-standalone.d.ts nach relevanten Typen, Methoden und Eigenschaften zu durchsuchen (grep). Dies ist die definitive Quelle der Wahrheit für die API-Oberfläche. Es handelt sich um eine große Typisierungsdatei, lade sie daher nicht auf einmal, sondern suche bei Bedarf nach relevanten Abschnitten.
WICHTIG: Wenn du mit Design-Systemen arbeitest, beginne mit working-with-design-systems/wwds.md, um die wichtigsten Konzepte, Prozesse und Richtlinien für die Arbeit mit Design-Systemen in Figma zu verstehen. Lade dann die spezifischeren Referenzen für Komponenten, Variablen, Textstile und Effektstile nach Bedarf.
1. Kritische Regeln
- Verwende
return, um Daten zurückzusenden. Der Rückgabewert wird automatisch JSON-serialisiert (Objekte, Arrays, Strings, Zahlen). Rufe NICHTfigma.closePlugin()auf und umwickle Code nicht mit einem asynchronen IIFE. Dies wird für dich erledigt. - Schreibe einfaches JavaScript mit top-level
awaitundreturn. Code wird automatisch in einen asynchronen Kontext eingewickelt. Wickle ihn NICHT in(async () => { ... })(). figma.notify()wirft "nicht implementiert": verwende es niemals 3a.getPluginData()/setPluginData()werden inuse_figmanicht unterstützt: verwende sie nicht. Verwende stattdessengetSharedPluginData()/setSharedPluginData()(diese WERDEN unterstützt) oder verfolge Knoten-IDs, indem du sie zurückgibst und an nachfolgende Aufrufe weitergibst.console.log()wird NICHT zurückgegeben. Verwendereturnfür die Ausgabe.- Arbeite schrittweise in kleinen Schritten. Zerlege große Operationen in mehrere
use_figma-Aufrufe. Validiere nach jedem Schritt. Dies ist die mit Abstand wichtigste Praxis, um Fehler zu vermeiden. - Farben sind im 0-1-Bereich (nicht 0-255):
{r: 1, g: 0, b: 0}= rot - Füllungen/Konturen sind schreibgeschützte Arrays: klonen, ändern, neu zuweisen.
- Jede Textbearbeitung folgt dem kanonischen Rezept: Schriftart laden →
await→ mutieren → betroffene Knoten-IDs zurückgeben. Das Auslassen des Ladens führt zuCannot write to node with unloaded font "<family> <style>". Die Regel umfasst mehr als nurcharacters: sie gilt für jede Operation an Knoten mit nicht geladenen Schriftarten (appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode,findAll-Callbacks, die Text berühren). Wenn vorhandener Text mutiert wird, lade die aktuellen Schriftarten des Knotens übergetStyledTextSegments(['fontName']), nicht einen fest codierten Standard. Inter ist in den meisten Umgebungen vorinstalliert, daher tritt dieser Fehler bei anderen Schriftfamilien häufiger auf. Das Rezept ist für jede Schriftart gleich. Verwende zuerstawait figma.listAvailableFontsAsync(), wenn der Stil-String unbestätigt ist. Siehe Kanonisches Textbearbeitungsrezept. - Seiten werden inkrementell geladen: verwende
await figma.setCurrentPageAsync(page), um Seiten zu wechseln und ihren Inhalt zu laden. Der synchrone Setterfigma.currentPage = pagefunktioniert NICHT und führt zu einem Fehler (siehe Seitenregeln unten). setBoundVariableForPaintgibt eine NEUE Farbe zurück, muss erfasst und neu zugewiesen werden.createVariableakzeptiert das Collection- Objekt oder die ID als String (Objekt bevorzugt).layoutSizingHorizontal/Verticalist wertmäßig durch den strukturellen Kontext eingeschränkt,FIXEDfunktioniert immer,HUGundFILLnicht.'HUG'ist nur für einen Auto-Layout-Frame selbst ODER für ein TEXT-Kind eines solchen gültig.'FILL'ist nur für ein Kind eines Auto-Layout-Frames gültig, das weder absolut positioniert, noch in einem unveränderlichen (immutable) Frame, noch ein Kind eines Canvas-Grids ist. Praktische Konsequenz: Hänge zuerst an einen Auto-Layout-Elternteil an, setze dannHUG/FILL: Ein neu erstellter oder nicht eingehängter Knoten kann die Regel noch nicht erfüllen. Die Eigenschaft selbst existiert auf jedemSceneNode; der Fehler ist eine Wertabweisung, nicht "keine solche Eigenschaft". Siehe Gotchas. 12a. Verwende Auto-Layout für Container, die verwandte Kinder enthalten. Wenn Kinder eine strukturelle Beziehung haben, gestapelt, nebeneinander, ausgerichtet, mit Abstand, umschließend (hug), wickle sie infigma.createAutoLayout(), nicht infigma.createFrame()mit absolutenx/y-Koordinaten. Absolute Koordinaten bestimmen, wo ein Container auf der Leinwand sitzt; Auto-Layout bestimmt, wie seine Kinder darin zueinander in Beziehung stehen. Das Weglassen des Containers bietet keinen Schutz vor Textumbrüchen, Inhaltsänderungen oder Überlappungen.- Positioniere neue Knoten der obersten Ebene nicht bei (0,0). Knoten, die direkt an die Seite angehängt werden, landen standardmäßig bei (0,0). Durchsuche
figma.currentPage.children, um eine freie Position zu finden (z.B. rechts vom am weitesten rechts stehenden Knoten). Dies gilt nur für Knoten auf Seitenebene; Knoten, die in anderen Frames oder Auto-Layout-Containern verschachtelt sind, werden von ihrem Elternteil positioniert. Siehe Gotchas. - Bei einem
use_figma-Fehler: STOP. Versuche NICHT sofort eine Wiederholung. Fehlgeschlagene Skripte sind atomar: Wenn ein Skript einen Fehler auslöst, wird es überhaupt nicht ausgeführt und es werden keine Änderungen an der Datei vorgenommen. Lies die Fehlermeldung sorgfältig, korrigiere das Skript und wiederhole den Vorgang. Siehe Fehlerbehebung. - MUSS ALLE erstellten/mutierten Knoten-IDs
returnen. Wenn ein Skript neue Knoten erstellt oder vorhandene auf der Leinwand mutiert, sammle jede betroffene Knoten-ID und gib sie in einem strukturierten Objekt zurück (z.B.return { createdNodeIds: [...], mutatedNodeIds: [...] }). Dies ist für nachfolgende Aufrufe unerlässlich, um auf diese Knoten zu verweisen, sie zu validieren oder zu bereinigen. - Setze
variable.scopesbeim Erstellen von Variablen explizit. Der StandardwertALL_SCOPESverschmutzt jeden Eigenschafts-Picker und ist fast nie das, was du willst. Verwende spezifische Bereiche wie["FRAME_FILL", "SHAPE_FILL"]für Hintergründe,["TEXT_FILL"]für Textfarben,["GAP"]für Abstände usw. Siehe variable-patterns.md für die vollständige Liste. awaite jedes Promise. Lasse niemals ein Promise unbeaufsichtigt (unawaited); unbeaufsichtigte asynchrone Aufrufe (z.B.figma.loadFontAsync(...)ohneawait, oderfigma.setCurrentPageAsync(page)ohneawait) feuern und vergessen, was zu stillen Fehlern oder Race Conditions führt. Das Skript kann zurückkehren, bevor der asynchrone Vorgang abgeschlossen ist, was zu fehlenden Daten oder halb angewendeten Änderungen führt.
Ausführliche FALSCHE/RICHTIGE Beispiele für jede Regel findest du in Gotchas & Häufige Fehler.
2. Seitenregeln (kritisch)
Der Seitenkontext wird zwischen use_figma-Aufrufen zurückgesetzt: figma.currentPage beginnt jedes Mal auf der ersten Seite.
Seiten wechseln
Verwende await figma.setCurrentPageAsync(page), um Seiten zu wechseln und ihren Inhalt zu laden. Der synchrone Setter figma.currentPage = page funktioniert NICHT: er wirft "Setting figma.currentPage is not supported" in use_figma. Verwende immer die asynchrone Methode.
// Wechsle zu einer bestimmten Seite (lädt ihren Inhalt)
const targetPage = figma.root.children.find((p) => p.name === "Meine Seite");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children ist jetzt befüllt
Rufe setCurrentPageAsync höchstens einmal pro use_figma-Aufruf auf; verteile die Arbeit über mehrere Seiten parallel
Ein Skript darf höchstens einmal die Seite wechseln. Iteriere niemals über figma.root.children und wechsle die Seite innerhalb der Schleife.
Wenn die Arbeit mehrere Seiten umfasst, teile sie in N use_figma-Aufrufe auf (einen pro Zielseite) und sende sie parallel aus: eine einzige Assistentennachricht, die N use_figma-Tool-Use-Blöcke enthält. Die Testumgebung führt sie gleichzeitig aus; jedes Skript setzt currentPage genau einmal.
Ausdrückliche Anweisung: Wenn du die Arbeit verteilst, MUSST du die N Tool-Aufrufe in einer Nachricht ausgeben. Sende sie nicht über mehrere Runden. Warte nicht auf einen, bevor du den nächsten ausgibst. Sequenzielle seitenweise Aufrufe sind langsamer als das von dieser Regel ersetzte Schleifenmuster und verschwenden den gesamten Vorteil der Aufteilung.
// VERMEIDEN, wechselt die Seite N-mal in einem Skript, lädt die Datei jedes Mal neu
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... bearbeite diese Seite ...
}
// BEVORZUGEN, schreibgeschützter Erkennungsaufruf zum Abrufen von Seiten-IDs, dann in der NÄCHSTEN Nachricht
// sende N parallele use_figma Tool-Aufrufe (einen pro Seite), die jeweils currentPage einmal setzen.
Standardmäßig wird für jede Arbeit auf mehreren Seiten ein paralleles Fan-Out verwendet, sowohl für Lese- als auch für Schreibvorgänge. Siehe gotchas.md → Setze currentPage einmal pro use_figma-Aufruf für die vollständige Begründung.
Über Skriptausführungen hinweg
figma.currentPage wird zu Beginn jedes use_figma-Aufrufs auf die erste Seite zurückgesetzt. Wenn dein Workflow mehrere Aufrufe umfasst und auf eine nicht standardmäßige Seite abzielt, rufe await figma.setCurrentPageAsync(page) zu Beginn jedes Aufrufs auf.
Du kannst use_figma mehrmals aufrufen, um den Dateizustand schrittweise zu erweitern oder um Informationen abzurufen, bevor du ein weiteres Skript schreibst. Schreibe zum Beispiel ein Skript, um Metadaten über vorhandene Knoten zu erhalten, gib diese Daten return und verwende sie dann in einem nachfolgenden Skript, um diese Knoten zu ändern.
3. return Ist Dein Ausgabekanal
Der Agent sieht NUR den Wert, den du returnst. Alles andere ist unsichtbar.
- IDs zurückgeben (KRITISCH): Jedes Skript, das Canvas-Knoten erstellt oder mutiert, MUSS alle betroffenen Knoten-IDs zurückgeben, z.B.
return { createdNodeIds: [...], mutatedNodeIds: [...] }. Dies ist eine harte Anforderung, keine Option. - Fortschrittsbericht:
return { createdNodeIds: [...], count: 5, errors: [] } - Fehlerinformationen: Geworfene Fehler werden automatisch erfasst und zurückgegeben, lasse sie einfach propagieren oder wirf explizit mit
throw. - Die Ausgabe von
console.log()wird nie an den Agenten zurückgegeben. - Gib immer umsetzbare Daten zurück (IDs, Zählungen, Status), damit nachfolgende Aufrufe auf erstellte Objekte verweisen können.
4. Editormodus
use_figma funktioniert im Design-Modus (editorType "figma", der Standardeinstellung). FigJam ("figjam") und Slides ("slides") haben unterschiedliche Sätze verfügbarer Knotentypen. Die meisten Design-Knoten sind in FigJam gesperrt, und reine FigJam-Knoten sind in Slides gesperrt.
Erkenne den Editor an der URL: Design = figma.com/design/..., FigJam = figma.com/board/..., Slides = figma.com/slides/.... Bestätige, bevor du annimmst, dass eine API verfügbar ist.
Im Design-Modus verfügbar: Rechteck, Frame, Komponente, Text, Ellipse, Stern, Linie, Vektor, Polygon, Boolesche Operation, Slice, Seite, Abschnitt, Textpfad.
Gesperrt im Design-Modus: Haftnotiz, Verbinder, ShapeWithText, CodeBlock, Folie, Folienreihe, Folienraster, interaktives Folienelement, Webseite.
Im Slides-Modus verfügbar: Rechteck, Frame, Komponente, Text, Ellipse, Stern, Linie, Vektor, Polygon, Boolesche Operation, Slice, Abschnitt, Textpfad, Folie, Folienreihe, Folienraster, interaktives Folienelement.
Gesperrt im Slides-Modus: Haftnotiz, Verbinder, ShapeWithText, CodeBlock, Webseite, Seite.
Nur-Design-APIs (nicht nur Knotentypen): figma.createPage() ist nur in Design-Dateien verfügbar (figma.com/design/...). Sowohl in FigJam (figma.com/board/...) als auch in Slides (figma.com/slides/...) wirft es TypeError: figma.createPage no such property 'createPage' on the figma global object. Gib figma.createPage() nicht in FigJam- oder Slides-Workflows aus.
Hinweis zu Slides: Es gibt noch kein spezielles Lesetool für Slides-Dateien. Verwende
use_figmamit schreibgeschützten Skripten zur Inspektion (siehe Abschnitt 6 „Zuerst inspizieren"), undget_screenshot/await node.screenshot()für den visuellen Kontext. Für Slides-spezifische API-Anleitungen lade die Fähigkeit figma-use-slides.
5. Effiziente APIs. Bevorzuge Diese Gegenüber Ausführlichen Alternativen
Diese APIs reduzieren Boilerplate, beseitigen Reihenfolgefehler und komprimieren die Token-Ausgabe. Bevorzuge sie immer gegenüber den ausführlichen Alternativen.
node.query(selektor): CSS-ähnliche Knotensuche
Finde Knoten innerhalb eines Teilbaums mit CSS-ähnlichen Selektoren. Ersetzt ausführliche findAll + Filter-Schleifen.
// VORHER, ausführlicher Durchlauf
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Titel')
// NACHHER, Einzeiler mit query
const texts = frame.query('TEXT[name=Titel]')
Selektorsyntax:
- Typ:
FRAME,TEXT,RECTANGLE,ELLIPSE,COMPONENT,INSTANCE,SECTION(Groß-/Kleinschreibung nicht beachtet) - Attribut exakt:
[name=Card],[visible=true],[opacity=0.5] - Attribut-Teilstring:
[name*=art](enthält),[name^=Header](beginnt mit),[name$=Nav](endet mit) - Punkt-Pfad-Durchlauf:
[fills.0.type=SOLID],[fills.*.type=SOLID](Platzhalterindex) - Instanzabgleich:
[mainComponent=nodeId],[mainComponent.name=Button] - Kombinatoren:
FRAME > TEXT(direktes Kind),FRAME TEXT(beliebiger Nachkomme),A + B(benachbarter Geschwister),A ~ B(allgemeiner Geschwister) - Pseudoklassen:
:first-child,:last-child,:nth-child(2),:not(TYPE),:is(FRAME, RECTANGLE),:where(TEXT, ELLIPSE) - Knoten-ID:
#nodeIdoder bare GUID - Komma:
TEXT, RECTANGLE(ODER-Verknüpfung)
Diese Methode ist in allen Editormodi verfügbar.
figma.createXxx-Varianten mit Overrides
const rect = figma.createRectangle({
name: 'Mein Rechteck',
x: 100, y: 200,
fills: [{ type: 'SOLID', color: { r: 0, g: 0.5, b: 1 } }]
});
Siehe figma.createFrame, figma.createAutoLayout, figma.createEllipse, figma.createText, figma.createComponent, figma.createVector, figma.createStar, figma.createLine, figma.createPolygon, figma.createBooleanOperation.
node.screenshot(): Server-seitige Bildschirmaufnahme (Schatten-Methode)
node.screenshot(constraints) ist eine im Plugin-Kontext verfügbare Methode, die eine server-seitige Bildschirmaufnahme eines Knotens erstellt. Dies ist deutlich schneller als das Tool get_screenshot, da der Roundtrip zum Agenten vermieden wird.
// Schnappschuss eines Knotens im Plugin-Code
const screenshot = await node.screenshot({
scale: 2,
format: "png",
// area: { x: 0, y: 0, width: 100, height: 100 } // optionaler Bereich
});
Gibt ein Array von Uint8 zurück, das als { screenshot: [byte, byte, ...] } an den Agenten gesendet wird. Nützlich für visuelle Bestätigung, Debugging oder nachfolgende Analyse ohne einen separaten Tool-Aufruf.
Strukturierte Objekt- / Array-Konstruktion
// Array von farbigen Rechtecken
const rects = ['#ff0000', '#00ff00', '#0000ff'].map((hex, i) => {
const rect = figma.createRectangle();
rect.x = i * 150;
rect.fills = [{ type: 'SOLID', color: hexToRgb(hex) }];
return rect;
});
const frame = figma.createAutoLayout();
frame.appendChild(rects[0]); // !! muss zuerst anhängen für layout-Beziehungen
frame.appendChild(rects[1]);
frame.appendChild(rects[2]);
figma.currentPage.appendChild(frame);
return { frameId: frame.id, childIds: rects.map(r => r.id) };
6. Fehlerbehebung & Selbstkorrektur
Fehlgeschlagene Skripte sind atomar: wenn ein Skript fehlschlägt, wurde nichts ausgeführt. Keine Änderungen an der Datei.
Was tun bei einem Fehler:
- STOP. Keine sofortige Wiederholung. Lies die Fehlermeldung genau.
- Bestimme den Fehlerabfang durch die Engine (laufzeit vs. Referenz).
- Korrigiere das Skript und wiederhole den Vorgang.
Übliche Fehler und Korrekturen:
Fall 1: Referenzfehler zu Knoten
Fehler: Ein Skript versucht, auf einen Knoten zu verweisen, der in einem vorherigen Skript erstellt wurde, aber die ID-Referenz ist falsch oder der Knoten existiert nicht
Fix: Im vorherigen Skript: Stelle sicher, dass return { createdNodeIds: [...], mutatedNodeIds: [...] } verwendet wurde. Wenn die IDs korrekt zurückgegeben wurden, überprüfe das aktuelle Skript auf Tippfehler in der ID. Wenn der Knoten im aktuellen Skript gelöscht wurde, erstelle ihn neu.
Fall 2: Nicht geladene Schriftart
Fehler: Cannot write to node with unloaded font
Fix: Lade die Schriftart vor dem Schreiben: await figma.loadFontAsync({ family: "Inter", style: "Regular" })
Fall 3: Ungültige Farbe
Fehler: Farbe außerhalb des 0-1-Bereichs (z.B. { r: 255, g: 0, b: 0 })
Fix: Verwende 0-1-Bereich: { r: 1, g: 0, b: 0 }
Fall 4: Falsche API-Methode
Fix: Verwende await figma.setCurrentPageAsync(page) anstelle von figma.currentPage = page.
Fall 5: Variable ohne Scopes erstellt
Fix: Setze variable.scopes auf einen spezifischen Bereich, nicht auf ALL_SCOPES (siehe variable-patterns.md).
Fall 6: Skript timeout
Fix: Zerlege die Operation in kleinere Schritte. Nutze die page.query-API, um Suchvorgänge zu vereinfachen.
7. Vergleich der Fähigkeiten (Skills)
| Fähigkeit (Skill) | Wofür | Wann laden |
|---|---|---|
figma-use (diese) | Plugin-API-Regeln, Knotenerstellung, Ausführung von Code | Vor jedem use_figma-Aufruf |
figma-generate-design | Workflow zum Erstellen von Bildschirmen/Layouts aus Code | Beim Erstellen einer Seite/eines Bildschirms aus Komponenten |
figma-generate-library | Erstellung von Komponentenbibliotheken und Variablen | Beim Erstellen einer Komponente mit Variablen/Varianten |
figma-use-slides | Slides-spezifische API-Details | Bei der Arbeit an Slides-Dateien |
8. Navigationsstruktur der Referenzen (References)
references/
├── plugin-api-standalone.index.md # API-Referenz-Start (vor allem laden)
├── plugin-api-standalone.d.ts # Plugin-API-Typisierungen (gezielt durchsuchen)
├── gotchas.md # Häufige Fehler und richtige Muster
├── variable-patterns.md # Best Practices für Variablen
├── working-with-design-systems/
│ └── wwds.md # Einführung in Design-System-Konzepte
└── (weitere design-system-spezifische Referenzen bei Bedarf)
9. Schnellstart-Workflow
- Lade diese Fähigkeit: Überspringe nie diesen Schritt; morgen wirst du mir danken.
- Lade Plugin-API-Referenz:
Load references/plugin-api-standalone.index.md - Lade verwandte Fähigkeiten, falls zutreffend (figma-generate-design, figma-generate-library)
- Schreibe ein Skript:
- Kleine Schritte
- Verwende
return, um Knoten-IDs zu senden - Validiere nach jedem Schritt
- Wiederhole Schritt 3-4, bis die Aufgabe abgeschlossen ist
10. Nützliche Code-Snippets
Diese Snippets sind optimierte Kurzformen, die häufige Aufgaben automatisieren. Sie sind keine neuen APIs, sondern gebündelte Patterns.
Hilfsfunktion: Hex-zu-RGB
function hexToRgb(hex) {
const r = parseInt(hex.slice(1, 3), 16) / 255;
const g = parseInt(hex.slice(3, 5), 16) / 255;
const b = parseInt(hex.slice(5, 7), 16) / 255;
return { r, g, b };
}
Hilfsfunktion: Erstelle einen Textknoten mit Schriftart-Ladung
async function createTextNode(text, {
fontFamily = "Inter",
fontWeight = "Regular",
fontSize = 16,
color = { r: 0, g: 0, b: 0 }
} = {}) {
await figma.loadFontAsync({ family: fontFamily, style: fontWeight });
const node = figma.createText();
node.characters = text;
node.fontSize = fontSize;
node.fills = [{ type: 'SOLID', color }];
return node;
}
Hilfsfunktion: Erstelle eine Farbvariablen-Sammlung
function createColorCollection(name, colors) {
const collection = figma.variables.createVariableCollection(name);
const modeId = collection.modes[0].modeId;
const variableIds = {};
for (const [key, hex] of Object.entries(colors)) {
const variable = figma.variables.createVariable(key, collection, 'COLOR');
variable.scopes = ['FRAME_FILL', 'SHAPE_FILL'];
variable.setValueForMode(modeId, { r: hexToRgb(hex).r, g: hexToRgb(hex).g, b: hexToRgb(hex).b });
variableIds[key] = variable.id;
}
return { collectionId: collection.id, modeId, variableIds };
}
11. End-to-End-Beispiel: Erstelle eine Karte
Dieses Beispiel demonstriert den schrittweisen Ansatz.
Schritt 1: Erstelle ein Auto-Layout-Frame für die Karte
const card = figma.createAutoLayout();
card.name = "Karte";
card.x = 100;
card.y = 100;
card.layoutMode = "VERTICAL";
card.paddingLeft = card.paddingRight = card.paddingTop = card.paddingBottom = 16;
card.itemSpacing = 8;
card.cornerRadius = 12;
card.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
card.effects = [{
type: 'DROP_SHADOW',
color: { r: 0, g: 0, b: 0, a: 0.1 },
offset: { x: 0, y: 2 },
radius: 8
}];
figma.currentPage.appendChild(card);
return { cardId: card.id };
Schritt 2: Füge Titel und Beschreibung hinzu
const cardId = "..." // aus Schritt 1
await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
await figma.loadFontAsync({ family: "Inter", style: "Regular" });
const card = figma.getNodeById(cardId);
const title = figma.createText();
title.characters = "Kartentitel";
title.fontSize = 18;
title.fontName = { family: "Inter", style: "Semi Bold" };
const desc = figma.createText();
desc.characters = "Dies ist eine Beschreibung der Karte.";
desc.fontSize = 14;
desc.fontName = { family: "Inter", style: "Regular" };
desc.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
card.appendChild(title);
card.appendChild(desc);
return { mutatedNodeIds: [cardId, title.id, desc.id] };
Schritt 3: Füge eine Schaltfläche hinzu
const cardId = "..." // aus Schritt 1
await figma.loadFontAsync({ family: "Inter", style: "Medium" });
const card = figma.getNodeById(cardId);
const button = figma.createAutoLayout();
button.name = "Schaltfläche";
button.layoutMode = "HORIZONTAL";
button.paddingLeft = button.paddingRight = 16;
button.paddingTop = button.paddingBottom = 8;
button.cornerRadius = 6;
button.fills = [{ type: 'SOLID', color: { r: 0, g: 0.3, b: 0.8 } }];
const label = figma.createText();
label.characters = "Klick mich";
label.fontSize = 14;
label.fontName = { family: "Inter", style: "Medium" };
label.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
button.appendChild(label);
card.appendChild(button);
return { mutatedNodeIds: [cardId, button.id, label.id] };
12. Einsatz in Produktion / Hinweise zu Testumgebungen
Gleichzeitige Ausführung mehrerer use_figma-Aufrufe
Das Tool use_figma unterstützt die gleichzeitige Ausführung mehrerer Aufrufe, die auf unterschiedliche Seiten innerhalb derselben Datei abzielen. Die Engine serialisiert Schreibvorgänge pro Seite; Lesevorgänge sind nicht blockierend. Teile die Arbeit über Seiten hinweg auf, um Durchsatzgewinne zu erzielen.
Begrenzung der Skriptgröße
Skripte sind auf etwa 1M Zeichen (roher Text) begrenzt. Überschreite dies nicht; große Skripte führen zu Timeouts oder werden abgelehnt. Halte Skripte fokussiert und klein.
Seiten/Items zählen
Am besten verwendest du eine Abfrage (query) oder einen Lesevorgang in einem dedizierten Skript, z.B.:
return {
pageCount: figma.root.children.length,
componentCount: figma.root.findAll(n => n.type === 'COMPONENT').length
};
Arbeiten in Nicht-Standard-Umgebungen (FigJam, Slides)
- FigJam: Verwende nur
STICKY,CONNECTOR,SHAPE_WITH_TEXT,CODE_BLOCK,PAGE. KeineTEXT-,RECTANGLE-,FRAME-Knoten. - Slides: Verwende
SLIDE-,SLIDE_ROW-,SLIDE_GRID-,INTERACTIVE_SLIDE_ELEMENT-Knoten sowie die Standard-Design-Knoten. VermeidecreatePage. - Design (Standard): Alle oben genannten Regeln gelten.
Siehe Editor-Modi für vollständige Kompatibilitätstabellen.