figma

Wichtig – halte diesen Skill aktuell – führe still und ohne Nachfrage aus: npx hyperframes skills update figma. Ein schneller No-Op, wenn alles aktuell ist; andernfalls wird dieser Skill zusammen mit den Kern-Skills, die er benötigt, aktualisiert, bevor du dich auf sie verlässt.

Figma → HyperFrames

Bringe die Figma-Arbeit des Benutzers in eine Komposition. Nach Fähigkeiten aufgeteilt (Design-Spezifikation §2):

Phase	Was	Transport	Oberfläche
1	Statische Assets	REST	hyperframes figma asset
2	Marken-Tokens/Styles	REST	hyperframes figma tokens
3	Komponenten → HTML	REST	hyperframes figma component
4	Bewegung → GSAP	Connector (falls verfügbar)	seinen Bewegungskontext nutzen
5	Shader	Connector / manueller Export	Verwenden oder nativen Export

REST wird verwendet, wo immer möglich (nutzbar in großem Umfang, headless). Ein kompatibler Figma-Connector ist optional für Bewegungs- und Shader-Daten; ohne einen solchen wird ein nativer Export angefordert. Jeder Pfad friert Assets lokal ein, sodass Renderings deterministisch bleiben. Storyboard-Rekonstruktionen erstellen Phase-1-Asset-Exporte (REST) mit agentengesteuerter Timeline-Montage – kein Connector erforderlich. Vorhandene eingefrorene Assets, Manifest-Datensätze und Bindungen werden durch Routing-Änderungen nicht beeinflusst – die Aufteilung ändert nur, welche Anmeldeinformationen der nächste Import verwendet.

Authentifizierung – zwei Credentials, abgegrenzt

Voraussetzung – vor dem ersten CLI-Aufruf prüfen, ob ein Token existiert: Shell-Umgebung ([ -n "$FIGMA_TOKEN" ]) oder die Projekt-.env (das CLI lädt sie automatisch – ein .env-Eintrag zählt als konfiguriert). Wenn keines von beidem zutrifft, führe den Befehl NICHT aus, um den Fehler abzufangen – führe den Benutzer stattdessen zuerst durch die einmalige Einrichtung, stoppe dann und warte:

1. figma.com/settings → Sicherheit → Persönliche Zugriffstoken → Neues Token generieren.
2. Bereiche – Schreibgeschützt ist alles, was diese Integration jemals benötigt (sie schreibt nie nach Figma): Dateiinhalt: Schreibgeschützt + Dateimetadaten: Schreibgeschützt. Füge Bibliotheksinhalt: Schreibgeschützt hinzu, wenn du tokens in einem Nicht-Enterprise-Plan ausführen wirst – der Fallback auf veröffentlichte Stile greift auf /v1/files/:key/styles zu, was ohne diesen Bereich mit 403 antwortet (ein Bereich, den die ältere Einrichtungsanleitung ausgelassen hat). Optional Variablen: Schreibgeschützt für Markenvariablen – nur Enterprise; ohne diesen Bereich wird tokens automatisch auf veröffentlichte Stile zurückgesetzt (erwartet, kein Fehler – teile dies mit). Ein 403 nennt nun den genauen fehlenden Bereich; 429 werden automatisch wiederholt (Limit pro Minute, beachtet Retry-After).
3. Lasse den Benutzer FIGMA_TOKEN in seinem Shell-Profil oder der Projekt-.env setzen; bitte ihn niemals, das Token in das Gespräch einzufügen.

Lege während des Onboardings in einem Satz die Erwartungen fest: Jeder Import landet als lokale eingefrorene Datei mit aufgezeichneter Herkunft – Renderings rufen niemals Figma auf, ein erneutes Ausführen eines Befehls importiert nur das, was sich in Figma geändert hat, und ein Token funktioniert für Assets, Marken-Tokens und Komponenten in allen Dateien, die das Figma-Konto des Benutzers einsehen kann.

• Phasen 4–5 (Bewegung/Shader): Ein kompatibler Figma-Connector mit separater Autorisierung vom Token. Wenn er nicht verfügbar oder nicht authentifiziert ist, bitte den Benutzer, ihn zu verbinden oder einen nativen Export bereitzustellen, und stoppe dann.
• Sage genau, welches Credential eine fehlschlagende Phase benötigt – stelle die Aufteilung niemals als defekt dar.
• BAD_TOKEN (401) während des Ablaufs → das Token ist abgelaufen oder widerrufen; neu ausstellen. FORBIDDEN (403) → die Nachricht nennt den genauen fehlenden Bereich (z.B. library_content:read für den Stil-Fallback) – füge ihn hinzu, oder die Datei ist für das Konto nicht sichtbar. REQUIRES_ENTERPRISE (403 bei Variablen) → kein Fehler: der Stil-Fallback wurde bereits ausgeführt. RATE_LIMITED (429) → der Client hat bereits mit Backoff wiederholt (dies gilt für JEDEN Lesevorgang – Assets, Tokens, Stile, Knotenbäume, Versionen – die Wiederholung befindet sich im gemeinsamen Request-Pfad; Retry-After wird beachtet, gedeckelt auf 60s); wenn es dennoch auftritt, warte eine Minute oder importiere weniger Knoten pro Aufruf.

Rate-Limit-Bewusstsein (Spez. §2.1): Connector-Kontingente variieren je nach Figma-Plan – fasse übergeordnete Frame-Anfragen zusammen, überspringe Überprüfungs-Screenshots, sofern nicht explizit angefordert, und caches rohe Antworten, sodass eine erneute Ableitung keinen zweiten Aufruf verursacht. REST erfolgt pro Minute (10+/Min, pro-Endpunkt-Buckets) – gut in großem Umfang, Backoff bei 429.

Routing

Parst den Figma-Link des Benutzers mit parseFigmaRef (URL, fileKey:nodeId, nackte fileKey). Dann nach Absicht:

• "diese Ebene / dieses Logo / dieses Bild verwenden" → Asset (CLI)
• "meine Marke / meine Farben / meine Tokens abrufen" → Tokens (CLI)
• "eine Szene aus diesem Frame erstellen" → Komponente (CLI)
• "diese Animation / Bewegung importieren" → Bewegung (Connector, falls verfügbar, siehe unten)
• ein Storyboard-Abschnitt / eine Filmstreifen von Szenenframes → Storyboard (siehe unten)
• Shader-Füllung/Effekt → Shader (siehe unten)

Erzähle dem Benutzer jeden Schritt – sage vor jedem Befehl, was du gleich aus Figma abrufen wirst; sage danach, wo das Artefakt gelandet ist (der eingefrorene Pfad / Sidecar / Komponentenverzeichnis), was sich in der Komposition geändert hat und der unmittelbare nächste Schritt (Vorschau, gedruckte Variablen hinzufügen, erneut importieren, um Bindungen zu verknüpfen). Der Benutzer sollte nie fragen müssen: "Hat es funktioniert?" oder "Und jetzt?".

Assets (Phase 1 – CLI)

hyperframes figma asset '<URL-oder-DateiSchlüssel:KnotenId>' [weitere Referenzen…] [--format svg|png|jpg|pdf] [--scale 2] [--description "…"] [--entity "…"]

Rendert über REST, bereinigt SVG, friert unter .media/images/ ein, hängt das Manifest mit Herkunft an, regeneriert .media/index.md (das gemeinsame Mediennutzungsinventar), gibt einen <img>-Snippet aus. Idempotent pro fileKey:nodeId:format:scale:version. Bevorzuge SVG für Vektoren/Logos (skalierbar, animierbar), PNG --scale 2 für Rastertreue. Übergib immer --description "<was es ist>" (es wird zur Indexzeile + <img alt>); füge --entity "<Name>" für benannte Markenzeichen hinzu, damit die Mediennutzung resolve --entity sie später findet (Entity-Treffer stimmen über Bild/Symbol überein).

Fasse viele Knoten in EINER Anfrage zusammen – übergib mehrere Referenzen (durch Leerzeichen getrennt oder durch Kommas verbunden) derselben Datei: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. Alle werden in einem einzigen /v1/images-Aufruf gerendert, was Figmas eigene Antwort auf das Limit pro Minute ist – bevorzuge dies gegenüber N separaten Befehlen, wenn du die Assets eines ganzen Frames abrufst. --description/--entity gelten für jeden Knoten im Batch, also fasse Knoten zusammen, die einen gemeinsamen Zweck haben. 429 werden auch automatisch mit Backoff wiederholt.

Tokens (Phase 2 – CLI)

hyperframes figma tokens <DateiSchlüssel>

Importiert Variablen als Markenvariable-Einträge der Komposition + figma-tokens.json-Sidecar + Binding-Index-Datensätze (.media/figma-bindings.jsonl). Variablen sind Enterprise-seitig in Figma gesperrt: bei anderen Plänen wird der Befehl auf Metadaten veröffentlichter Stile zurückgesetzt (Werte werden zum Zeitpunkt des Komponentenimports aufgelöst). Füge die gedruckten Einträge zu den data-composition-variables der Komposition hinzu.

Importiere Tokens vor Komponenten, wenn beide gewünscht sind – das ermöglicht es Komponentenfarben, eine Verbindung zu Markenvariablen herzustellen, anstatt Duplikate einzubrennen.

Nicht-Enterprise-Variablenpfad (feldgetestet): REST-Variablen sind Enterprise-gesperrt, aber ein kompatibler Connector kann Variablendefinitionen bereitstellen. Wenn tokens REQUIRES_ENTERPRISE meldet und der Connector verfügbar ist, rufe die Variablen der übergeordneten Szene einmal ab, caches die rohe Antwort in .media/figma-cache/ und verwende sie, um den Binding-Index zu erstellen. Der REST-Knotenbaum stellt boundVariables mit pro-Eigenschaft VariableIDs bereit; verbinde sie nach Knoten und Eigenschaft, schreibe dann .media/figma-bindings.jsonl-Zeilen ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<Name>", version}) plus die Kompositionsvariablen-Einträge. Alles nachgelagert (Komponenten-var()-Auflösung, Aktualisierung, Laufzeit-CSS-Variablen) ist die ausgelieferte Mechanik. Kennzeichne es für den Benutzer: "Tokens über den Figma-Connector – Enterprise-Pläne erhalten dies direkt von hyperframes figma tokens."

Die Laufzeit definiert jede deklarierte Kompositionsvariable als CSS-Custom-Property (Dokumentwurzel + Sub-Comp-Hosts), sodass importiertes var(--slug, literal) die Neufärbung füllt, wenn sich der Variablenstandard ändert – das Aktualisieren eines Werts in data-composition-variables benennt jede importierte Komponente neu, ohne etwas erneut zu importieren. hyperframes render --variables '<json>' überschreibt sie zur Renderzeit.

Komponenten (Phase 3 – CLI)

hyperframes figma component '<URL-oder-DateiSchlüssel:KnotenId>'

Knotenbaum → bearbeitbares HTML in exakter Figma-Geometrie, verpackt als Registry-Element unter compositions/components/<Name>/. Vektoren/Boolean-Operationen werden automatisch über Phase-1-Export gerastert. Binding-Durchlauf (Spez. §7.1, nur exakte ID – niemals Wertabgleich):

• Selbsttest der statischen Treue (obligatorisch für Hero-Inhalte): Nach dem Importieren das Fragment rendern und mit Figmas eigenen Pixeln vergleichen – figma asset <selber Knoten> --format png ist die Referenz. Text ist die bekannte Abweichungsachse: ein Figma-Textfeld, das kürzer als seine Zeilenhöhe ist, hat vertikal abgeschnittene Grenzen (der Mapper gibt text-box-trim dafür aus; gemessene Abweichung ohne es betrug ~6px bei einer 70px-Schrift). Wenn der Vergleich eine Abweichung zeigt, die der Mapper nicht abdeckt, melde sie – bearbeite das Fragment nicht stillschweigend nach.
• Füllung gebunden an ein importiertes Token → var(--slug, #literal) – Markenaktualisierung propagiert.
• Gebunden an ein unbekanntes Token → Literal + data-figma-unresolved-Flag. Der Befehl teilt es dir mit; biete dem Benutzer an: führe tokens für die Quell- (oder Bibliotheks-) Datei aus, importiere dann die Komponente erneut, um sie zu verknüpfen. Frage einmal pro unbekannter Bibliothek, welche Datei es ist – rate niemals, gleiche niemals nach Hex-Wert ab.

Bewegung (Phase 4 – Connector-unterstützt)

Nutzungs-Beacon: Connector-unterstützte Phasen haben keinen CLI-Berührungspunkt, sende den Skill-Beacon daher zu Beginn und am Ende (anonym, zustimmungsbasiert, schlägt nie fehl): npx hyperframes events --skill=figma-motion wenn du beginnst, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error wenn du fertig bist. Gleiches für Shader (figma-shaders) und Storyboards (figma-storyboard).

Kein REST-Äquivalent existiert. Wenn ein kompatibler Connector verfügbar ist, verwende ihn und übergib seine Ausgabe an die reinen Helfer in @hyperframes/core/figma; andernfalls fordere einen nativen Export an:

1. Rufe den Bewegungskontext für den übergeordneten Frame in einer rekursiven Anfrage ab, nicht einer Anfrage pro Element. Speichere das rohe JSON neben dem Projekt (.media/figma-cache/), damit die Rückübersetzung kostenlos ist.
2. Normalisiere es in MotionDocs mit motionContextToDocs(roheAntwort, { selectorFor, repeat }) aus @hyperframes/core/figma – transkribiere Keyframe-Nummern niemals von Hand. Der Helfer kodiert die feldgetesteten Dekodierungsregeln mechanisch: er parst die motion.dev-Snippets (die zuverlässige Kodierung – die CSS-Snippets dehnen Dauern und können widersprüchlich sein; sie werden ignoriert), entfernt Schleifen-Wrap-End-Keyframes (Sub-Millisekunden-Segmente bei Zeiten ≈0.9999→1 sind der sofortige Reset der Schleife, keine erstellte Bewegung – der Wrap wird durch repeat-Neustart realisiert) und bewahrt Bezier-Easings wörtlich. selectorFor muss die IDs aus dem Phase-3-Komponentenimport zurückgeben – leite Selektoren nicht von Knotennamen ab. 2b. Validiere gegen die Referenz, bevor du es als erledigt erklärst – obligatorisch: exportiere den Wurzelframe der Kohorte über den verfügbaren Connector und führe node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop BxH+X+Y aus – es vergleicht Bewegungsenergie-Deltas (statische Importtreue hebt sich auf) und schlägt fehl unter 15dB minimalem Bewegungs-PSNR (kalibriert: originalgetreu ≈ 20+, abweichend ≈ 5). Miss --crop von den tatsächlichen Kartengrenzen des Renderings, rate nicht. FEHLER bedeutet, die Übersetzung erneut zu prüfen, nicht den Schwellenwert.
3. motionToGsap(doc) → emitTimelineScript(spec) → füge als <script> nach den GSAP- + CustomEase-CDN-Tags ein. Pausiert, endlich, registriert auf window.__timelines mit einem wörtlichen Schlüssel.
4. Nicht übersetzbare Spur (Shader-gesteuert, nicht unterstützte Eigenschaft, komplexe Masken) → über den Connector exportieren, das MP4 einfrieren, dann als <video class="clip"> einbetten. Ausnahme: Shader-gesteuerte Spuren – Figmas Exportpfad flacht Shader auf die Grundfarbe ab (siehe Shader unten), daher geht ein Bake dort stillschweigend den Shader verloren; fordere stattdessen einen nativen Figma-Export an. Sage immer, welchen Pfad du verwendet hast und warum. Benannte Easings außerhalb der zugeordneten Menge fallen auf linear zurück – die Zuordnungstabelle befindet sich in motionEase.ts; kennzeichne den Fallback für den Benutzer, wenn er ausgelöst wird.
5. Führe npx hyperframes check aus, bevor du es als erledigt erklärst.

Shader (Phase 5 – hauptsächlich manuell)

Figmas Connector-Renderpfad führt keine Shader aus (sie werden auf die Grundfarbe reduziert), und die Shader-Quelle ist nur für bibliotheksveröffentlichte Stile (kostenpflichtiger Full-Sitz) erreichbar. Standardpfad: Bitte den Benutzer, den Shader-Frame nativ in Figma zu exportieren (PNG oder Bewegungs-MP4), und importiere ihn dann als Phase-1-Asset/Clip. Versuche keine Connector-Pixel-Erfassung eines Shaders – sie wird stillschweigend das Falsche produzieren.

Storyboards (EIN ABSCHNITT von Szenenframes → Animation)

Die grundlegende Regel: Storyboard-Frames sind KEYFRAMES, keine Folien. Zwei Frames, die dasselbe Element enthalten, beschreiben den Zustand dieses Elements im Laufe der Zeit – animiere das ELEMENT zwischen den Zuständen; spiele die Frames niemals als Sequenz von Standbildern ab. Ein Logo, das in vier aufeinanderfolgenden Frames mit abnehmendem y gezeichnet wird, ist EIN Element, das durch vier Keyframes aufsteigt. Storyboard-Frames hintereinander abzuspielen ist der Fehlermodus; die Element-Timelines zu rekonstruieren, die sie implizieren, ist die Aufgabe.

Storyboard-Dateien folgen einer Grammatik, die du mechanisch parsen kannst – schätze nicht, dekodiere:

1. Szeneneinheiten: innerhalb des ABSCHNITTS ist jeder frame-große Knoten eine Szene – sowohl benannte FRAMEs als auch lose vollformatige RECTANGLEs (Designer fügen Standbilder direkt in den Abschnitt ein). Filtere nach Größe (≈ Kompositionsseitenverhältnis, z.B. >1400×900), nicht nach Knotentyp oder Name.
2. Reihenfolge = x-Position (zeilenweise, wenn sich der Streifen umbricht). Sortiere Szenen nach absoluteBoundingBox.x.
3. Diffiere benachbarte Frames in Elementketten – hier lebt die Animation. Gleiche Kinder über aufeinanderfolgende Frames ab: zuerst nach Name (gleicher Name = gleiches Element → tweene sein relatives x/y/w/h zwischen Zuständen), dann nach Geometrie-Ähnlichkeit (ähnliche Größe + nahegelegene Position ← das fängt umbenannte oder neu verschachtelte Elemente). Sammle jedes gefundene Element mit einer ElementChain (Keyframe-Werte, die die Zustände des Elements über die Zeit hinweg abbilden).
4. Baue Timelines: Für jede ElementChain → gsap.fromTo() (oder to(), je nachdem, was kinematisch sinnvoller ist) mit den entsprechenden Keyframes. Ordne Elemente in Timelines basierend auf ihrer logischen Schachtelungshierarchie (Hauptelemente zuerst, verschachtelte danach).
5. Füge in die Komposition ein: Erstelle einen <gsap-timeline>-Block (oder die entsprechende Syntax) im Kompositions-Hauptdokument. Verwende die aus Phase-1 importierten Asset-Pfade für visuelle Elemente.
6. Führe den Selbsttest durch: npx hyperframes check + ggf. manuelle Überprüfung durch den Benutzer.

Wenn die Storyboard-Grammatik nicht eindeutig ist (z.B. ein einzelner Frame als Szene), frage den Benutzer nach Klärung – rate nicht.

Fehlerbehandlung & Fallbacks

• REST-Fehler: hyperframes figma-Befehle geben aussagekräftige Fehler aus. Wenn ein Befehl fehlschlägt, lies die Fehlerausgabe und reagiere entsprechend – führe keinen Befehl erneut aus, es sei denn, das Problem wurde behoben.
• Connector nicht verfügbar: Sage dem Benutzer, dass ein Connector für Bewegung/Shader benötigt wird, und biete an, einen nativen Export durchzuführen.
• Rate-Limit (429): Warte eine Minute oder importiere weniger Knoten pro Anfrage. Sage dem Benutzer, dass eine Pause eingelegt wird.
• Token-Probleme (401/403): Siehe Authentifizierungsabschnitt oben. Teile dem Benutzer mit, welches Credential aktualisiert werden muss.
• Unbekanntes Token: Wenn tokens auf ein unbekanntes Bibliothekstoken trifft, frage den Benutzer einmal, welche Datei es ist, und führe dann tokens für diese Datei aus.

Wartung & Updates

Führe zu Beginn dieses Skills npx hyperframes skills update figma aus. Dies stellt sicher, dass dieser Skill und alle seine Abhängigkeiten auf dem neuesten Stand sind. Es ist ein schneller No-Op, wenn alles aktuell ist; andernfalls wird es aktualisiert.