bdsanxz/figma-access

Figma-Zugriff

Du arbeitest mit Figma über ein einziges Kommandozeilen-Werkzeug. Es gibt KDL aus und speichert seine Datendateien als .kdl: ein Node pro Zeile, mit den einfachen Feldern eines Nodes als Schlüssel=Wert in dieser Zeile, sodass grep, awk und sed direkt darauf funktionieren. Ausnahmen sind spec (eigene einzeilige Textübersicht), daemon log (gibt die Log-Zeilen des Daemons unverändert aus), sowie render, screenshot, image-fills und compare (speichern Bilddateien; die Zusammenfassung auf stdout ist dennoch KDL). Es hat zwei Zugangswege:

• REST (file, node, spec, render, image-fills, api): Liest jede Datei anhand ihrer URL mit dem Token des Benutzers. Es muss nichts geöffnet sein. Lesevorgänge werden lokal zwischengespeichert und bei Rate-Limits wiederholt.
• Plugin (exec, screenshot, selection, logs, changes, call): Ein Hintergrund-Daemon kommuniziert mit dem Desktop Bridge Plugin, das in Figma Desktop läuft. Nur so kannst du eine Datei ändern. Dein Hauptwerkzeug ist exec, das Figma Plugin API JavaScript in der Datei ausführt.

references/tips.md enthält Lektionen aus echten Durchläufen, nach Situation geordnet. Sie sind Leitlinien, keine Regeln: Lies den Abschnitt für deine Situation und passe ihn an.

Regeln

• Zeige niemals den Token. Gib ihn nicht aus, logge ihn nicht; teste ihn mit figma-access api /v1/me.
• Überprüfe vor und nach jeder Änderung. Beurteile jedes sichtbare Ergebnis anhand eines Bildes, nicht anhand des erzeugenden Codes.
• Lies Werte, rate nicht; der Render entscheidet. Entnimm Farben, Größen, Abstände, Schriftarten und Text der Datei, niemals einem Bild nach Augenmaß. Wenn Daten und Render unterschiedlich sind, zählt, was der Benutzer sieht.
• Ändere nur, was der Benutzer verlangt. Lesen ist immer in Ordnung. Lösche oder überschreibe niemals vorhandene Arbeit, es sei denn, die Anfrage sagt das.
• Ein Timeout ist kein Fehler. Figma kann ein laufendes Skript nicht stoppen; überprüfe logs und die Datei, bevor du es erneut ausführst.

Arbeitsablauf

1. Einrichtung

1. <skill> ist das Verzeichnis dieser SKILL.md. Führe das Werkzeug aus als bun <skill>/scripts/figma-access.js BEFEHL ...; diese Datei schreibt es als figma-access BEFEHL .... Es läuft mit Bun, nicht mit Node: Starte es immer mit bun, nie mit node, und führe auch eigene JavaScript- oder TypeScript-Helfer mit bun aus. Um den Befehl zu verkürzen, definiere zu Beginn jedes Shell-Aufrufs eine Shell-Funktion (fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...), keine Variable: zsh zerlegt eine Variable nicht in Wörter. Setze jede URL und Node-ID in Anführungszeichen: ?, & und ; sind für die Shell speziell. Fehlt bun, sage dem Benutzer, er solle es von https://bun.sh installieren, und brich ab.
2. Führe figma-access --help einmal aus, und figma-access <befehl> --help vor der ersten Verwendung jedes Befehls. Exit-Codes: 0 ok, 1 Figma meldete einen Fehler, 2 falsche Argumente, 3 Daemon, Plugin oder Token nicht verfügbar. "Die Ausgabe lesen" in references/tips.md erklärt das Format und die Suche.
3. Wähle den Pfad aus der Anfrage, wie "Einen Pfad wählen" in references/tips.md beschreibt: eine URL und ein reiner Lesejob → REST; jede Änderung an der Datei → Plugin; beide können zusammen verwendet werden.

2a. Verbindung über REST

1. Führe figma-access api /v1/me aus. Bei "kein Token": finde heraus, wo der Benutzer ihn gesetzt hat, und lade ihn im selben Befehl, wie "Token" in references/tips.md beschreibt. Frage den Benutzer nur nach einem Token (Figma: Einstellungen > Sicherheit > Persönliche Access Tokens, Dateiinhalte lesen), wenn keiner gesetzt ist.
2. Führe figma-access file <url> aus, um die Seiten und Top-Level-Frames zu sehen. Wähle den zu bearbeitenden Node gemäß "Den richtigen Node finden" in references/tips.md.

2b. Verbindung über das Plugin

1. Führe figma-access status aus. Es startet den Daemon bei Bedarf.
   • Dateien aufgelistet: weiter.
   • Keine Dateien: führe figma-access files aus, das auf das Plugin wartet. Wenn es mit 3 beendet wird, führe figma-access setup aus und gib dem Benutzer die steps in einfachen Worten: Importiere das Plugin einmal über den angegebenen Manifest-Pfad, führe dann Plugins > Development > Figma Desktop Bridge in der Datei aus und lasse das Fenster geöffnet. Bitte den Benutzer, Bescheid zu sagen, wenn es läuft, und führe dann erneut figma-access files aus.
2. Mehr als eine Datei verbunden: übergib bei jedem weiteren Befehl --file <fileKey>.

3. Das Design verstehen

1. Lese die kleinste Ansicht, die die Frage beantwortet, zuerst die Übersicht und Details nur dort, wo du arbeitest:
   • Struktur: figma-access node <url|key> <id> --outline 2 (REST), oder die Seitenübersicht-Rezepte in references/plugin-api.md (Plugin);
   • alles, was Code braucht, ein Node pro sichtbarer Zeile: figma-access spec <url|key> <id> -o <datei>; für einen großen Frame speichere es einmal mit node ... -o <datei> und gib bei jedem weiteren spec --from <datei> an, wie "Rate-Limits und der Cache" in references/tips.md beschreibt;
   • was der Benutzer mit "dies" oder "das Ausgewählte" meint: figma-access selection;
   • wie es aussieht: figma-access render <key> <id> (REST, exakte Größe) oder figma-access screenshot <id> (Plugin), dann öffne das Bild.
2. Lese die reports von node: Schriftarten, Bildfüllungen und wie viele verborgene Ebenen entfernt wurden. Lese "Verborgene Ebenen" und "Ein Design-Bild lesen" in references/tips.md.
3. Bei Komponenten, Varianten, Variablen und Stilen lies ihre tatsächliche Struktur, bevor du sie änderst oder kopierst, und verwende Vorhandenes wieder, anstatt Duplikate zu erstellen.

4. Die Aufgabe erledigen

Ein Design in Code umsetzen. Bevor du Code schreibst, lies „Vom Design zum Code“ in references/tips.md: die meisten Unterschiede, die nach einem ersten Build übrig bleiben (Bildzuschnitte, Schriftarten, Textversätze, Seitenbreite), sind dort abgedeckt. Schreibe den Code dort hin, wo der Benutzer oder sein Projekt es vorsieht (der von ihnen genannte Pfad oder die eigene Struktur des Projekts); _swe/figma-access/ enthält nur Arbeitsartefakte wie Renders, gespeicherte Node-Dateien, Specs, Screenshots und Skripte.

1. Rendere den Frame im Maßstab 1 als Referenz und lies ihn in Teilen, wenn er hoch ist.
2. Schreibe die spec des Frames in eine Datei, mit --origin an der Ecke, wo der Seiteninhalt beginnt, und entnimm jeden Wert daraus. Rendere Bilder und das, was als ICON oder MASKED markiert ist, statt sie neu zu bauen. Baue Auto-Layout-Frames aus der Richtung, dem Abstand, dem Padding und der Größe, die spec ausgibt, anstatt aus ihren gespeicherten Boxen, und platziere die Kinder von Gruppen und Frames ohne Auto Layout an ihren Boxen. Positioniere nicht jeden Node absolut an seiner gespeicherten Box, weder von Hand noch mit einem Generator: Diese Seite kopiert jede veraltete Box, bricht, wenn ein Text länger wird, und kann sich nicht an das Fenster anpassen. Überprüfe jeden als LAYOUT DRIFT markierten Teil am Render.
3. Liste die Schriftarten mit jeder Stärke auf; suche im Projekt nach den Dateien aller nicht öffentlichen Familien und frage den Benutzer in einer Nachrage nach den noch fehlenden sowie nach allem, was du aus der Datei nicht entnehmen kannst. Bis sie eintreffen, oder wenn du nicht fragen kannst, verwende einen Platzhalter und teile das mit.
4. Lasse Geräte- oder Browser-Chrome weg und lasse die Seite sich an das Fenster anpassen: Die Breite des Frames ist der Bildschirm, für den er gezeichnet wurde; Hintergründe und Trennlinien erstrecken sich über das Fenster und die Inhaltsspalte ist zentriert, es sei denn, der Benutzer wünscht eine feste Breite.
5. Baue Abschnitt für Abschnitt, dann messe die Seite gegen die Referenz mit figma-access compare <reference.png> <seite> --nodes <node-datei> --wide <px>: Es erfasst die Seite, gibt die unterschiedlichen Pixel pro Abschnitt des Frames mit der Verschiebung aus, die jeden erklärt, wie weit jeder Textstil und Node abweicht und welche fehlen, schreibt ein Differenzbild und überprüft ein breiteres Fenster. Mit --nodes entnimmt es die Abschnitte den eigenen Kindern des Frames und schneidet eine Referenz zu, die der Schatten des Frames verbreitert hat. Sieh dir auch die Aufnahme und das Differenzbild an und wiederhole, bis jeder Abschnitt übereinstimmt. Wenn der Benutzer ein pixelgenaues oder 1:1-Ergebnis wünscht und ein Skill dafür in deiner Sitzung aufgeführt ist, verwende es mit diesen Renders als Designbilder.

Die Datei ändern. Über das Plugin:

1. Schreibe die Änderung als Plugin-API-Code und führe sie mit figma-access exec aus, gemäß references/plugin-api.md für API-Vorgaben und Platzierung. Langer Code kommt in eine Arbeitsdatei (z. B. unter _swe/figma-access/) und wird mit exec -f ausgeführt. Gib immer die ids der nächsten benötigten Nodes mit return zurück; füge --timeout 30s oder mehr für lange Arbeiten hinzu.
2. Für Aufgaben, die von vorgefertigten Plugin-Routinen abgedeckt werden (Komponenten-Sets, Lint- und Barrierefreiheits-Audits, Bildfüllungen, Annotationen, FigJam- und Slides-Helfer), verwende figma-access call <METHODE> '<json>'; figma-access methods <filter> listet die Parameter auf.
3. Lies jedes Mal die Ausgabe: bei ok #false behebe die Ursache und entferne Teilarbeit vor dem Wiederholen; bei warning unter resultAnalysis überprüfe ids und Namen; für die eigene Ablaufverfolgung des Skripts verwende figma-access logs --since 2m.
4. Erstelle einen Screenshot von jedem Node, den du erstellt oder geändert hast (--scale 2 für kleine), und überprüfe ihn gegen die Anfrage. Korrigiere und erstelle erneut einen Screenshot; wenn nach drei Runden immer noch Abweichungen bestehen, teile dem Benutzer mit, was noch offen ist und warum.

"Durch das Plugin arbeiten" in references/tips.md deckt ab, was hier meistens schiefgeht.

5. Bericht

Teile dem Benutzer mit, was du gelesen oder geändert hast, mit Node-Namen und -IDs, sowie den Pfaden der Renders, Screenshots und Dateien, die du geschrieben hast. Nenne alles, was du nicht getan hast, jede Annahme, die du getroffen hast (eine Ersatzschriftart, eine übersprungene verborgene Ebene, weggelassener Chrome), und was nicht verifiziert wurde.

Fehlerbehebung

• "Rate limit exceeded" (429): Das CLI hat bereits gewartet und es erneut versucht. Folge "Rate-Limits und der Cache" in references/tips.md und warte eine Minute vor dem nächsten großen Lesevorgang.
• Exit 3, keine Datei verbunden: Das Plugin läuft nicht in dieser Datei oder sucht noch (es überprüft alle paar Sekunden). Bitte den Benutzer, es erneut auszuführen. figma-access daemon log zeigt Verbindungen, sobald sie eintreten.
• Ein anderes Werkzeug verwendet dasselbe Plugin (z. B. figma-console-mcp): Beide laufen nebeneinander; figma-access status zeigt, ob dieser Daemon die Datei hat.
• Veraltetes Verhalten nach Skill-Aktualisierung: Führe figma-access setup erneut aus, bitte den Benutzer, das Manifest in Figma neu zu importieren, und führe dann figma-access daemon restart aus.
• "Plugin disconnected before it answered": Der Benutzer hat das Plugin oder die Datei geschlossen, oder das Plugin hat neu geladen. Überprüfe die Datei, bevor du die Änderung wiederholst.