Bildschirme und Ansichten aus dem Designsystem erstellen / aktualisieren
Verwende dieses Skill, um Bildschirme, Ansichten und mehrteilige UI-Container in Figma zu erstellen oder zu aktualisieren, indem du das veröffentlichte Designsystem wiederverwendest: Komponenten, Variablen und Styles, anstatt Grundelemente mit hartcodierten Werten zu zeichnen. Dies umfasst vollständige Seiten, Modale, Dialoge, Drawer, Sidebars, Panels und jede zusammengesetzte Ansicht mit mehreren Abschnitten. Die Kernidee: Die Figma-Datei enthält wahrscheinlich ein veröffentlichtes Designsystem mit Komponenten, Farb-/Abstandsvariablen und Text-/Effekt-Styles, die den UI-Komponenten und Tokens der Codebasis entsprechen. Finde und verwende diese, anstatt Boxen mit Hex-Farben zu zeichnen.
PFLICHT: Du MUSST vor jedem use_figma-Aufruf auch figma-use laden. Dieses Skill enthält kritische Regeln (Farbspektren, Schriftarten laden usw.), die für jedes von dir geschriebene Skript gelten.
Übergib immer skillNames: "figma-generate-design", wenn du use_figma im Rahmen dieses Skills aufrufst. Dies ist ein Protokollierungsparameter. Er hat keine Auswirkung auf die Ausführung.
Skill-Grenzen
- Verwende dieses Skill, wenn das Ergebnis eine zusammengesetzte Figma-Ansicht (neu oder aktualisiert) ist, z. B. vollständige Bildschirmseiten, Modale, Dialoge, Drawer, Sidebars, Panels oder andere mehrteilige Container, die aus Designsystem-Komponenteninstanzen erstellt werden.
- Wenn der Benutzer neue wiederverwendbare Komponenten oder Varianten erstellen möchte, verwende direkt figma-use.
- Wenn der Benutzer Code Connect-Zuordnungen schreiben möchte, wechsle zu figma-code-connect.
Voraussetzungen
- Figma MCP-Server muss verbunden sein
- Die Ziel-Figma-Datei muss ein veröffentlichtes Designsystem mit Komponenten haben (oder Zugriff auf eine Team-Bibliothek)
- Der Benutzer sollte entweder Folgendes bereitstellen:
- Eine Figma-Datei-URL / Datei-Key, in der gearbeitet werden soll
- Oder Kontext darüber, welche Datei das Ziel ist (der Agent kann Seiten erkennen)
- Quellcode oder Beschreibung des zu erstellenden/aktualisierenden Bildschirms/der Ansicht
Paralleler Workflow mit generate_figma_design (nur Web-Apps)
Wenn ein Bildschirm aus einer Web-App erstellt wird, die im Browser gerendert werden kann, werden die besten Ergebnisse erzielt, indem beide Ansätze parallel ausgeführt werden:
- Parallel:
- Beginne mit dem Erstellen des Bildschirms mit diesem Workflow (use_figma + Designsystem-Komponenten)
- Führe
generate_figma_designaus, um einen pixelgenauen Screenshot der laufenden Web-App zu erfassen
- Sobald beide abgeschlossen sind: Aktualisiere die use_figma-Ausgabe so, dass sie dem pixelgenauen Layout aus der
generate_figma_design-Erfassung entspricht. Die Erfassung liefert die genauen Abstände, Größen und visuellen Behandlungen, die angestrebt werden sollen, während deine use_figma-Ausgabe ordnungsgemäße Komponenteninstanzen hat, die mit dem Designsystem verknüpft sind. Wenn die Erfassung Bilder enthält, übertrage sie in deine use_figma-Ausgabe, indem duimageHash-Werte aus den Bildfüllungen der Erfassung kopierst (siehe Schritt 5 für Details). - Sobald bestätigt, dass es gut aussieht: Lösche die
generate_figma_design-Ausgabe. Sie wurde nur als visuelle Referenz verwendet.
Dies kombiniert das Beste aus beiden Welten: generate_figma_design liefert pixelgenaue Layout-Genauigkeit, während use_figma ordnungsgemäße Designsystem-Komponenteninstanzen erzeugt, die verknüpft und aktualisierbar bleiben.
Dieser parallele Workflow ist PFLICHT, wenn die Quelle Bilder enthält. Die use_figma-Plugin-API kann keine externen Bild-URLs abrufen. Sie kann Bildfüllungen nur setzen, indem sie imageHash-Werte von Knoten kopiert, die bereits in der Datei vorhanden sind. generate_figma_design rastersiert alle sichtbaren Bilder in Figma und liefert die benötigten Hashes. Wenn du die Erfassung überspringst, wenn Bilder vorhanden sind, bleiben Bildrahmen leer.
Für Nicht-Web-Apps (iOS, Android usw.) oder beim Aktualisieren vorhandener Bildschirme verwende den Standard-Workflow unten.
Erforderlicher Workflow
Befolge diese Schritte in der Reihenfolge. Überspringe keine Schritte.
Harte Gates, verbotene Abkürzungen:
- Verboten:
search_design_systemfür Komponenten-Schlüssel, bis 2a-i abgeschlossen ist und 2a-ii versucht oder als N/A protokolliert wurde (z. B. "leere Datei, keine vorhandenen Bildschirme").- Verboten: Jeder
use_figma-Aufruf, der die Leinwand verändert (Schritt 3+), bis alle Zeilen in Schritt 2 der Checkliste unten ausgefüllt sind.
Schritt 1: Verstehe das Ergebnis
Bevor du Figma berührst, verstehe, was du baust:
- Wenn aus Code gebaut wird, lies die relevanten Quelldateien, um die Struktur, Abschnitte und verwendeten Komponenten zu verstehen.
- Identifiziere die Hauptabschnitte der Ansicht (z. B. für eine Seite: Kopfzeile, Hero, Inhaltsbereiche, Fußzeile; für ein Modal: Titelzeile, Formularabschnitte, Aktionsleiste; für eine Sidebar: Navigation, Inhaltsbereich, Fußzeilenaktionen).
- Liste für jeden Abschnitt die beteiligten UI-Komponenten auf (Schaltflächen, Eingabefelder, Karten, Navigations-Pills, Akkordeons usw.).
- Überprüfe, ob die Ansicht Bilder enthält (z. B.
<img>,<Image>, Hintergrundbilder, Produktfotos, Avatare, von URLs geladene Icons). Wenn dies der Fall ist und es sich um eine Web-App handelt, musst du den parallelengenerate_figma_design-Erfassungs-Workflow ausführen. Starte ihn sofort zusammen mit Schritt 2, damit die Erfassung läuft, während du Komponenten entdeckst. Siehe "Paralleler Workflow mit generate_figma_design" oben.
Schritt 2: Sammle Komponenten-Schlüssel, Variablen und Styles
Du benötigst drei Dinge aus dem Designsystem: Komponenten (Schaltflächen, Karten usw.), Variablen (Farben, Abstände, Radien) und Styles (Text-Styles, Effekt-Styles wie Schatten). Harte Hex-Farben oder Pixelwerte nicht verwenden, wenn Designsystem-Token vorhanden sind.
2a: Komponenten entdecken
2a-i. PFLICHT: Überprüfe Code Connect für benötigte Komponenten. Ausgehend von der Komponentenliste aus Schritt 1 überprüfe für jede Komponente, ob es eine Code Connect-Datei in der Codebasis gibt. Code Connect-Dateien befinden sich neben der Komponentenquelle und sind nach Plattform benannt:
- TypeScript/JS:
*.figma.ts,*.figma.js - React (parser-basiert):
*.figma.tsx - Kotlin/Compose:
.kt-Dateien, die@FigmaConnectenthalten - Swift:
.swift-Dateien, dieFigmaConnectenthalten
Für jede benötigte Komponente (z. B. Button, Card, Input) suche nach ihrer Code Connect-Datei, globbe oder greppe nach dem Komponentennamen (z. B. **/Button.figma.tsx, **/Card.figma.ts). Lies nur Dateien, die zu tatsächlich benötigten Komponenten passen.
Extrahiere aus jeder passenden Code Connect-Datei die Figma-Komponenten-URL. Parse fileKey und nodeId aus der URL (konvertiere Bindestriche in Doppelpunkte: 123-456 → 123:456). Löse dann Komponenten-Schlüssel über use_figma auf:
Beispiel: Code Connect-Datei enthält // url=https://figma.com/design/ABC123/File?node-id=609-35535. Parse fileKey = ABC123, nodeId = 609:35535. Führe use_figma gegen die Bibliotheksdatei (fileKey ABC123, nicht die Zieldatei) aus, um den Schlüssel aufzulösen:
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
Bündele mehrere Lookups in einem einzigen Aufruf. Verwende die zurückgegebenen Schlüssel mit importComponentSetByKeyAsync() in Schritt 4.
Markiere aufgelöste Komponenten. Wenn alle Komponenten aufgelöst sind, überspringe 2a-ii und 2a-iii. Wenn keine der benötigten Komponenten Code Connect-Dateien hat, fahre mit 2a-ii fort.
2a-ii. PFLICHT, wenn noch nicht aufgelöste Komponenten vorhanden sind: Überprüfe vorhandene Bildschirme. Prüfe, ob die Zieldatei bereits Bildschirme enthält, die dasselbe Designsystem verwenden. Ein einzelner use_figma-Aufruf, der durch die Instanzen eines vorhandenen Rahmens läuft, gibt dir eine exakte, maßgebliche Komponentenübersicht:
// Schreibgeschützte Erkennung, überspringe unsichtbare Inhalte innerhalb von Instanzen (ausgeblendete
// Varianten usw.) für die hunderte Male schnellere findAllWithCriteria.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
const mc = inst.mainComponent;
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
const key = cs ? cs.key : mc?.key;
const name = cs ? cs.name : mc?.name;
if (key && !uniqueSets.has(key)) {
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
}
});
return [...uniqueSets.values()];
Vergleiche die Ergebnisse mit deinen nicht aufgelösten Komponenten. Markiere neu aufgelöste. Wenn alle Komponenten aufgelöst sind, überspringe 2a-iii.
2a-iii. LETZTER AUSWEG: search_design_system. Nur, wenn Komponenten nach Abschluss von sowohl 2a-i als auch 2a-ii nicht aufgelöst sind.
Rufe vor der Suche get_libraries auf, um zu entdecken, welche Bibliotheken für die Datei verfügbar sind. Dies gibt zwei Listen zurück: bereits zur Datei hinzugefügte Bibliotheken und Bibliotheken, die hinzugefügt werden können (Community-UI-Kits und Organisationsbibliotheken). Jeder Eintrag enthält einen libraryKey, den du an search_design_system über den Parameter includeLibraryKeys übergeben kannst, um deine Suche auf bestimmte Bibliotheken zu beschränken, anstatt alles zu durchsuchen.
// Schritt 1: Verfügbare Bibliotheken entdecken
get_libraries({ fileKey })
// Rückgabe: {
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// Schritt 2: Suche innerhalb einer bestimmten Bibliothek mit ihrem libraryKey
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })
Organisationsbibliotheken in libraries_available_to_add sind paginiert (20 pro Seite). Wenn libraries_available_to_add_next_offset nicht null ist, sind mehr Organisationsbibliotheken verfügbar. Rufe get_libraries erneut mit offset auf diesen Wert auf, um die nächste Seite abzurufen. Community-UI-Kits erscheinen nur auf der ersten Seite. Wenn der Benutzer eine bestimmte Bibliothek nennt, die du auf der aktuellen Seite nicht siehst, blättere weiter, bevor du aufgibst.
Dies ist besonders nützlich, wenn die Datei viele Bibliotheken hat und du gezielte Ergebnisse wünschst (z. B. nur innerhalb von "iOS 26" oder "Material 3" suchen, anstatt Übereinstimmungen aus jeder Bibliothek zu erhalten).
Suche breit: Probiere mehrere Begriffe und Synonyme aus (z. B. "button", "input", "nav", "card", "accordion", "header", "footer", "tag", "avatar", "toggle", "icon" usw.). Verwende includeComponents: true, um dich auf Komponenten zu konzentrieren.
Füge Komponenteneigenschaften in deine Übersicht ein. Du musst wissen, welche TEXT-Eigenschaften jede Komponente für Textüberschreibungen bereitstellt. Erstelle eine temporäre Instanz, lies ihre componentProperties (und die von verschachtelten Instanzen) und entferne dann die temporäre Instanz.
Beispiel für eine Komponentenübersicht mit Eigenschafteninformationen:
Komponentenübersicht:
- Button → key: "abc123", type: COMPONENT_SET
Eigenschaften: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
Eigenschaften: { "Device": VARIANT, "Variant": VARIANT }
Verschachteltes "Text Heading" hat: { "Text#2104:5": TEXT }
Verschachtelter "Button" hat: { "Label#2:0": TEXT }
2b: Variablen entdecken (Farben, Abstände, Radien)
Überprüfe zuerst vorhandene Bildschirme (wie bei Komponenten). Oder verwende search_design_system mit includeVariables: true.
WARNUNG: Zwei unterschiedliche Methoden zur Variablenentdeckung, nicht verwechseln.
use_figmamitfigma.variables.getLocalVariableCollectionsAsync(): gibt nur lokale Variablen zurück, die in der aktuellen Datei definiert sind. Wenn dies leer zurückgibt, bedeutet das nicht, dass keine Variablen existieren. Remote-/veröffentlichte Bibliotheksvariablen sind für diese API unsichtbar.search_design_systemmitincludeVariables: true: durchsucht alle verknüpften Bibliotheken, einschließlich Remote- und veröffentlichter. Dies ist das korrekte Werkzeug, um Designsystem-Variablen zu entdecken.Ziehe niemals den Schluss "keine Variablen existieren" allein aufgrund eines leeren Ergebnisses von
getLocalVariableCollectionsAsync(). Führe immer auchsearch_design_systemmitincludeVariables: trueaus, um nach Bibliotheksvariablen zu suchen, bevor du dich entscheidest, eigene zu erstellen.
Abfragestrategie: search_design_system vergleicht mit Variablennamen (z. B. "Gray/gray-9", "core/gray/100", "space/400"), nicht mit Kategorien. Führe mehrere kurze, einfache Abfragen parallel aus, anstatt eine zusammengesetzte Abfrage:
- Primitive Farben: "gray", "red", "blue", "green", "white", "brand"
- Semantische Farben: "background", "foreground", "border", "surface", "text"
- Abstände/Größen: "space", "radius", "gap", "padding"
Wenn erste Suchen leer zurückkommen, versuche kürzere Fragmente oder andere Namenskonventionen; Bibliotheken variieren stark ("grey" vs "gray", "spacing" vs "space", "color/bg" vs "background").
Untersuche die gebundenen Variablen eines vorhandenen Bildschirms für die maßgeblichsten Ergebnisse:
// Schreibgeschützte Erkennung, überspringe unsichtbare Instanz-Innenteile für Geschwindigkeit.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
// boundVariables können auf jedem Szenenknoten leben; jedes Szenentyp aufzuzählen,
// nur um findAllWithCriteria zu füttern, ist ungefähr dasselbe wie findAll(() => true)
// und ist viel lauter in der Skriptausgabe.
const uniqueIds = new Set(
frame.findAll(() => true).flatMap(n =>
Object.values(n.boundVariables ?? {})
.flatMap(b => Array.isArray(b) ? b : [b])
.map(b => b?.id)
.filter(Boolean)
)
);
const variables = await Promise.all(
[...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
.filter(Boolean)
.map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));
Importiere Bibliotheksvariablen (remote = true) mit figma.variables.importVariableByKeyAsync(key). Für lokale Variablen verwende direkt figma.variables.getVariableByIdAsync(id).
Siehe variable-patterns.md für Bindungsmuster.
2c: Styles entdecken (Text-Styles, Effekt-Styles)
Suche nach Styles mit search_design_system und includeStyles: true sowie Begriffen wie "heading", "body", "shadow", "elevation". Oder untersuche, was ein vorhandener Bildschirm verwendet:
// Schreibgeschützte Erkennung, überspringe unsichtbare Instanz-Innenteile für Geschwindigkeit.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const styles = { text: new Map(), effect: new Map() };
for (const node of frame.findAll(() => true)) {
if ('textStyleId' in node && node.textStyleId) {
const style = await figma.getStyleByIdAsync(node.textStyleId);
if (style && !styles.text.has(style.id)) {
// Prüfe auf Duplikate mit verschiedenen IDs, die auf denselben
// veröffentlichten Style verweisen
styles.text.set(style.id, { name: style.name, id: style.id, key: style.key });
}
}
if ('effectStyleId' in node && node.effectStyleId) {
const style = await figma.getStyleByIdAsync(node.effectStyleId);
if (style && !styles.effect.has(style.id)) {
styles.effect.set(style.id, { name: style.name, id: style.id, key: style.key });
}
}
}
return {
textStyles: [...styles.text.values()],
effectStyles: [...styles.effect.values()]
};
Veröffentlichte Styles (remote) müssen mit figma.importStyleByKeyAsync(key) importiert werden. Lokale Styles sind direkt über figma.getStyleByIdAsync(id) verwendbar.
Schritt 2-Checkliste
Bevor du mit Schritt 3 fortfährst, fülle diese Tabelle aus:
| Datenquelle | Status | Details |
|---|---|---|
| Code Connect (2a-i) | ☐ Versucht / ☐ Alle gelöst | Liste der gefundenen Komponenten-Schlüssel |
| Vorhandene Bildschirme (2a-ii / 2b / 2c) | ☐ Keine vorhanden / ☐ Gelesen | Zusätzlich gefundene Komponenten (2a-ii), Variablen (2b), Styles (2c) |
| Bibliothekssuche (2a-iii / 2b / 2c) | ☐ Versucht / ☐ Gelöst | Alle verbleibenden Komponenten, Variablen, Styles |
WENN KEINE DER QUELLEN ETWAS ERGIBT HAT, DANN WÄRE DIESE AUFGABE MIT DIESEM SKILL NICHT MACHBAR. Erwäge, stattdessen figma-use zu verwenden, um das Ziel mit Grundelementen und hartcodierten Werten zu zeichnen, und informiere den Benutzer, dass kein Designsystem gefunden wurde.
Schritt 3: Existierenden Bildschirm oder Abschnitt finden (oder Seite vorbereiten)
Je nachdem, ob du einen vorhandenen Bildschirm aktualisierst oder einen neuen erstellst:
- Vorhandenen Bildschirm aktualisieren: Finde seinen Rahmen (Frame) auf der Seite. Aktualisiere seine Komponenteninstanzen, Textfelder und Bindungen. Größenänderungen des Rahmens sind in Ordnung. Entferne nicht benötigte untergeordnete Elemente. Füge neue untergeordnete Elemente hinzu.
- Neuen Bildschirm erstellen: Wähle eine Seite. Wenn mehrere Seiten vorhanden sind, wähle die relevanteste. Füge einen neuen Rahmen (Frame) hinzu. Siehe
use_figma-Dokumentation für Details zum Rahmen-Hinzufügen.
Schritt 4: Bildschirm Abschnitt für Abschnitt aufbauen
Baue jede Ansicht Abschnitt für Abschnitt.
- Importiere Komponenten-Sets mit
importComponentSetByKeyAsync()(oderimportComponentsByKeyAsync()für einzelne Komponenten) und importiere erforderliche Styles/Variablen mitimportStyleByKeyAsync()/importVariableByKeyAsync(). - Platziere Komponenteninstanzen mit
inst.createInstance(). Setze Varianten (übersetProperties) und Textüberschreibungen (übersetProperties). Binde Variablen an Knoteneigenschaften mitsetBoundVariable. - Baue den Bildschirm Abschnitt für Abschnitt. Verschachtle Container innerhalb von Containern nach Bedarf.
Umgang mit Bildern
Wenn der Quellbildschirm Bilder enthält, und es war nicht möglich, den parallelen generate_figma_design-Workflow auszuführen (z. B. aufgrund einer Nicht-Web-App), dann muss der Benutzer eventuell auf Bildfüllungen aus vorhandenen Knoten kopieren. Schaue auf anderen Bildschirmen in derselben Datei nach vorhandenen Bildern, die erneut verwendet werden können. Kopiere imageHash-Werte von vorhandenen Füllungen (siehe Schritt 5).
WICHTIG:
use_figmakann KEINE Bilder von externen URLs laden. Es kann nur Bildfüllungen setzen, indem esimageHash-Werte von Knoten kopiert, die bereits in der Figma-Datei vorhanden sind.
Anwenden von Variablen
Wenn du eine Farbe oder einen Abstand auf eine Instanz- oder Formeigenschaft anwendest, erstelle zuerst eine Bindung:
const variable = figma.variables.importVariableByKeyAsync("variable_key_here");
instance.setBoundVariable("fill", variable);
Siehe variable-patterns.md für vollständige Dokumentation zu Bindungsmustern.
Auf keinen Fall hartcodierte Werte im gesamten Workflow verwenden.
Schritt 5: Erfassungsreferenz nutzen (wenn verwendet)
Wenn du den parallelen generate_figma_design-Workflow ausgeführt hast:
- Sobald die Erfassung abgeschlossen ist, platziere sie über deiner use_figma-Ausgabe, um Layout-Unterschiede zu überprüfen. Verwende die Erfassung als Overlay, um Abstände, Größen und visuelle Behandlungen zu verfeinern.
- Übertrage Bilder aus der Erfassung in deine use_figma-Ausgabe. Die Erfassung enthält Rahmendaten mit
imageHash-Werten. Erstelle Rechtecke (oder andere Formen) in deiner use_figma-Ausgabe mit demselbenimageHash, um die Bilder zu duplizieren:
// Lese zunächst die Erfassungsdaten, um imageHash-Werte zu finden.
// Verwende dann:
const rect = figma.createRectangle();
rect.fills = [{ type: "IMAGE", imageHash: hash_wert, scaleMode: "FILL" }];
- Sobald die Ausrichtung zufriedenstellend ist, lösche die Erfassung.
Schritt 6: Prüfen und Verfeinern
- Überprüfe den Bildschirm visuell (benutze das Figma-Plugin-Panel, falls verfügbar, oder bitte den Benutzer um Feedback).
- Stelle sicher, dass Abstände, Textüberschreibungen und Varianten korrekt sind.
- Wende abschließende Korrekturen basierend auf dem visuellen Vergleich mit der Quelle an (Quellcode, Screenshot oder Beschreibung).