Figma → HyperFrames

Plugin-Installationen: Befolgen Sie vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln, wenn sich diese Fähigkeit innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die untenstehenden Aktualisierungshinweise.

Zunächst – halten Sie diese Fähigkeit aktuell – bestätigen Sie mit dem Benutzer, bevor Sie es ausführen: npx hyperframes skills update figma. Ein schneller No-op, wenn alles aktuell ist; andernfalls wird diese Fähigkeit zusammen mit den abhängigen Kernbereichsfähigkeiten aktualisiert, bevor Sie sich auf sie verlassen.

Was macht Figma → HyperFrames?

Bringen Sie die Figma-Arbeit des Benutzers in eine Komposition. Aufgeteilt nach Fähigkeit (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 verwenden
5	Shader	Connector / manueller Export	Verwenden Sie es oder einen nativen Export

REST wird immer dort verwendet, wo es möglich ist (nutzbar bei hohem Volumen, headless). Ein kompatibler Figma-Connector ist für Bewegungs- und Shader-Daten optional; falls keiner vorhanden ist, fordern Sie einen nativen Export an. Jeder Pfad friert Assets lokal ein, sodass Rendervorgänge deterministisch bleiben. Storyboard-Rekonstruktionen setzen Phase-1-Asset-Exporte (REST) mit einer KI-gesteuerten Timeline-Montage zusammen – 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 Anmeldeinformationen, abgegrenzt

Vorab – überprüfen Sie vor dem ersten CLI-Aufruf, ob ein Token existiert: Shell-Umgebung ([ -n "$FIGMA_TOKEN" ]) oder die Projekt-.env (die CLI lädt sie automatisch – ein .env-Eintrag gilt als konfiguriert). Wenn beides nicht der Fall ist, führen Sie den Befehl NICHT aus, um den Fehler abzufangen – führen Sie den Benutzer stattdessen durch die einmalige Einrichtung, halten Sie dann an und warten Sie:

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 in Figma): Dateiinhalt: Schreibgeschützt + Dateimetadaten: Schreibgeschützt. Fügen Sie Bibliotheksinhalt: Schreibgeschützt hinzu, wenn Sie tokens in einem Nicht-Enterprise-Plan ausführen – der Fallback für veröffentlichte Styles trifft auf /v1/files/:key/styles, was ohne diesen Bereich 403 zurückgibt (ein Bereich, den die ältere Setup-Anleitung ausgelassen hat). Optional Variablen: Schreibgeschützt für Markenvariablen – nur Enterprise; ohne diesen Bereich greift tokens automatisch auf veröffentlichte Styles zurück (erwartet, kein Fehler – sagen Sie das). Ein 403 gibt jetzt den genauen fehlenden Bereich an; 429 werden automatisch wiederholt (pro-Minute-Limit, beachtet Retry-After).
3. Lassen Sie den Benutzer FIGMA_TOKEN in seinem Shell-Profil oder der Projekt-.env setzen; bitten Sie ihn niemals, das Token in das Gespräch einzufügen.

Setzen Sie während des Onboardings auch in einem Satz die Erwartungen: Jeder Import landet als lokale eingefrorene Datei mit aufgezeichneter Herkunft – Rendervorgänge rufen niemals Figma auf, das erneute Ausführen eines Befehls importiert nur, was sich in Figma geändert hat, und ein Token funktioniert für Assets, Marken-Tokens und Komponenten in jeder Datei, die ihr Figma-Konto 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, bitten Sie den Benutzer, ihn zu verbinden oder einen nativen Export bereitzustellen, und halten Sie dann an.
• Sagen Sie genau, welche Anmeldeinformationen eine fehlschlagende Phase benötigt – stellen Sie die Aufteilung niemals als defekt dar.
• BAD_TOKEN (401) während des Ablaufs → das Token ist abgelaufen/widerrufen; neu ausstellen. FORBIDDEN (403) → die Nachricht nennt den genauen fehlenden Bereich (z. B. library_content:read für den Styles-Fallback) – fügen Sie ihn hinzu, oder die Datei ist für das Konto nicht sichtbar. REQUIRES_ENTERPRISE (403 bei Variablen) → kein Fehler: der Styles-Fallback wurde bereits ausgeführt. RATE_LIMITED (429) → der Client hat es bereits mit Backoff versucht (dies gilt für JEDEN Lesevorgang – Assets, Tokens, Styles, Knotenbäume, Versionen – der Wiederholungsversuch befindet sich im gemeinsam genutzten Anforderungspfad; Retry-After wird beachtet, gedeckelt auf 60s); wenn es immer noch auftritt, warten Sie eine Minute oder importieren Sie weniger Knoten pro Aufruf.

Ratenbegrenzungsbewusstsein (Spezifikation §2.1): Connector-Kontingente variieren je nach Figma-Plan – bündeln Sie Parent-Frame-Anfragen, überspringen Sie Verifizierungs-Screenshots, sofern nicht danach gefragt, und cachen Sie rohe Antworten, sodass eine erneute Ableitung niemals einen zweiten Aufruf kostet. REST ist pro Minute (10+/Min., pro-Endpoint-Buckets) – bei Volumen in Ordnung, bei 429 zurückziehen.

Routing

Analysieren Sie den Figma-Link des Benutzers mit parseFigmaRef (URL, fileKey:nodeId, bloßes 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 / Filmstreifen von Szenenframes → Storyboard (siehe unten)
• Shader-Füllung/Effekt → Shader (siehe unten)

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

Assets (Phase 1 – CLI)

hyperframes figma asset '<url-or-fileKey:nodeId>' [weitere Ref…] [--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, generiert .media/index.md (das gemeinsame Mediennutzungsinventar) neu, gibt einen <img>-Snippet aus. Idempotent pro fileKey:nodeId:format:scale:version. Bevorzugen Sie SVG für Vektoren/Logos (skalierbar, animierbar), PNG --scale 2 für Rastertreue. Übergeben Sie immer --description "<was es ist>" (es wird die Indexzeile + <img alt>); fügen Sie --entity "<name>" für benannte Markenzeichen hinzu, damit die Mediennutzung resolve --entity sie später findet (Entity-Treffer stimmen über Bild/Symbol hinweg überein).

Bündeln Sie viele Knoten in EINER Anfrage – übergeben Sie mehrere Referenzen (leerzeichengetrennt oder kommagetrennt) 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 Ratenlimit pro Minute ist – bevorzugen Sie dies gegenüber N separaten Befehlen, wenn Sie die Assets eines gesamten Frames abrufen. --description/--entity gelten für jeden Knoten im Batch, also bündeln Sie Knoten, die einen gemeinsamen Zweck haben. 429 werden auch automatisch mit Backoff wiederholt.

Tokens (Phase 2 – CLI)

hyperframes figma tokens <fileKey>

Importiert Variablen als Kompositions-Markenvariablen-Einträge + figma-tokens.json Sidecar + Bindeindex-Datensätze (.media/figma-bindings.jsonl). Variablen sind auf Unternehmensebene vorgelagert gesperrt: Bei anderen Plänen greift der Befehl auf veröffentlichte Style-Metadaten zurück (Werte werden zum Zeitpunkt des Komponentenimports aufgelöst). Fügen Sie die gedruckten Einträge zur data-composition-variables der Komposition hinzu.

Importieren Sie Tokens vor Komponenten, wenn beides gewünscht ist – so können Komponentenfarben mit Markenvariablen verknüpft werden, anstatt Duplikate zu erstellen.

Nicht-Enterprise-Variablenpfad (feldgetestet): REST-Variablen sind auf Unternehmensebene gesperrt, aber ein kompatibler Connector kann Variablendefinitionen bereitstellen. Wenn tokens REQUIRES_ENTERPRISE meldet und der Connector verfügbar ist, rufen Sie die Variablen der übergeordneten Szene einmal ab, cachen Sie die rohe Antwort in .media/figma-cache/ und verwenden Sie sie zum Erstellen des Bindeindex. Der REST-Knotenbaum boundVariables liefert VariableIDs pro Eigenschaft; verknüpfen Sie sie nach Knoten und Eigenschaft, schreiben Sie dann .media/figma-bindings.jsonl-Zeilen ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) plus die Kompositionsvariablen-Einträge. Alles nachgelagerte (Komponenten-var()-Auflösung, Aktualisierung, Laufzeit-CSS-Variablen) ist die ausgelieferte Mechanik. Kennzeichnen Sie es für den Benutzer: „Tokens über den Figma-Connector – Enterprise-Pläne erhalten dies direkt von hyperframes figma tokens."

Die Laufzeit deklariert jede deklarierte Kompositionsvariable als CSS Custom Property (Dokumentstamm + Sub-Comp-Hosts), sodass importiertes var(--slug, #literal) die Umfärbung auffüllt, wenn sich der Variablenstandard ändert – das Aktualisieren eines Werts in data-composition-variables rebrandet jede importierte Komponente, ohne etwas erneut zu importieren. hyperframes render --variables '<json>' überschreibt sie zur Rendering-Zeit.

Komponenten (Phase 3 – CLI)

hyperframes figma component '<url-or-fileKey:nodeId>'

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

• Statischer Selbsttest der Wiedergabetreue (obligatorisch für Heldeninhalte): Rendern Sie nach dem Import das Fragment und vergleichen Sie es mit Figmas eigenen Pixeln – figma asset <selber Knoten> --format png ist die Ground Truth. Text ist die bekannte Driftachse: Ein Figma-Textfeld, das kürzer als seine Zeilenhöhe ist, vertikal abgeschnittene Grenzen (der Mapper gibt für diese text-box-trim aus; gemessene Drift ohne war ~6px bei einer 70px-Schriftart). Wenn der Vergleich eine Drift zeigt, die der Mapper nicht abdeckt, melden Sie es – justieren Sie das Fragment nicht stillschweigend nach.
• Füllung gebunden an einen importierten Token → var(--slug, #literal) – Markenaktualisierung propagiert.
• Gebunden an einen unbekannten Token → literal + data-figma-unresolved Flag. Der Befehl teilt es Ihnen mit; bieten Sie dem Benutzer an: Führen Sie tokens für die Quell- (oder Bibliotheks-) Datei aus, importieren Sie dann die Komponente erneut, um sie zu verknüpfen. Fragen Sie einmal pro unbekannter Bibliothek, welche Datei es ist – raten Sie niemals, gleichen Sie niemals nach Hex ab.

Bewegung (Phase 4 – Connector-unterstützt)

Nutzungsbeacon: Connector-unterstützte Phasen haben keinen CLI-Berührungspunkt, also feuern Sie den Skill-Beacon zu Beginn und am Ende (anonym, zustimmungsabhängig, schlägt niemals fehl): npx hyperframes events --skill=figma-motion zu Beginn, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error am Ende. Gleiches gilt für Shader (figma-shaders) und Storyboards (figma-storyboard).

Es gibt kein REST-Äquivalent. Wenn ein kompatibler Connector verfügbar ist, verwenden Sie ihn und übergeben Sie seine Ausgabe an die reinen Helfer in @hyperframes/core/figma; andernfalls fordern Sie einen nativen Export an:

1. Rufen Sie den Bewegungskontext für den übergeordneten Frame in einer rekursiven Anfrage ab, nicht einer Anfrage pro Element. Speichern Sie das rohe JSON neben dem Projekt (.media/figma-cache/), sodass die Rückübersetzung kostenlos ist.
2. Normalisieren Sie in MotionDocs mit motionContextToDocs(rawResponse, { selectorFor, repeat }) aus @hyperframes/core/figma – transkribieren Sie niemals Keyframe-Nummern von Hand. Der Helfer codiert die feldgetesteten Dekodierungsregeln mechanisch: Es parst die motion.dev-Schnipsel (die zuverlässige Kodierung – die CSS-Schnipsel dehnen Dauer und können abweichen; sie werden ignoriert), entfernt Loop-Wrap-Tail-Keyframes (Sub-Millisekunden-Segmente zu Zeiten ≈0,9999→1 sind der sofortige Reset der Schleife, keine erstellte Bewegung – der Wrap wird durch den repeat-Neustart realisiert) und bewahrt Bezier-Easen unverändert. selectorFor muss die IDs aus dem Phase-3-Komponentenimport zurückgeben – leiten Sie Selektoren nicht von Knotennamen ab. 2b. Validieren Sie gegen die Ground Truth, bevor Sie es als erledigt bezeichnen – obligatorisch: Exportieren Sie den Stammframe der Kohorte durch den verfügbaren Connector und führen Sie node <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y aus – es vergleicht Bewegungsenergie-Deltas (statische Importtreue hebt sich auf) und schlägt unter 15 dB minimaler Bewegungs-PSNR fehl (kalibriert: originalgetreu ≈ 20+, abweichend ≈ 5). Messen Sie --crop von den tatsächlichen Kartenrändern des Renderings, raten Sie nicht. FEHLER bedeutet, die Übersetzung zu überprüfen, nicht den Schwellenwert.
3. motionToGsap(doc) → emitTimelineScript(spec) → injizieren Sie als <script> nach den GSAP + CustomEase CDN-Tags. Pausiert, endlich, registriert auf window.__timelines mit einem Literalschlüssel.
4. Nicht übersetzbare Spur (Shader-gesteuert, nicht unterstützte Eigenschaft, komplexe Masken) → durch den Connector exportieren, das MP4 einfrieren, dann als <video class="clip"> einbetten. Ausnahme: Shader-gesteuerte Spuren – Figmas Exportpfad flacht Shader auf die Basisfarbe ab (siehe Shader unten), sodass ein Bake dort stillschweigend den Shader verliert; bitten Sie den Benutzer stattdessen um einen nativen Figma-Export. Sagen Sie immer, welchen Pfad Sie verwendet haben und warum. Benannte Eases außerhalb des abgebildeten Satzes fallen auf linear zurück – die Mapping-Tabelle lebt in motionEase.ts; kennzeichnen Sie den Fallback für den Benutzer, wenn er ausgelöst wird.
5. Führen Sie npx hyperframes check aus, bevor Sie es als erledigt bezeichnen.

Shader (Phase 5 – größtenteils manuell)

Figmas Connector-Renderpfad führt keine Shader aus (sie werden auf die Basisfarbe abgeflacht), und die Shader-Quelle ist nur für bibliotheksveröffentlichte Styles (bezahlter Full-Sitzplatz) erreichbar. Standardpfad: Bitten Sie den Benutzer, den Shader-Frame nativ in Figma zu exportieren (PNG oder Motion MP4), und importieren Sie ihn dann als Phase-1-Asset/Clip. Versuchen Sie keine Connector-Pixel-Erfassung eines Shaders – sie wird stillschweigend das Falsche erzeugen.

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 – animieren Sie das ELEMENT zwischen den Zuständen; spielen Sie die Frames niemals als eine Abfolge von Standbildern ab. Ein Logo, das in vier aufeinanderfolgenden Frames mit abnehmendem y gezeichnet wird, ist EIN Element, das durch vier Keyframes aufsteigt. Das Hintereinander-Abspielen von Storyboard-Frames ist der Fehlermodus; die Rekonstruktion der Element-Timelines, die sie implizieren, ist die Aufgabe.

Storyboard-Dateien folgen einer Grammatik, die Sie mechanisch parsen können – schauen Sie nicht mit bloßem Auge, dekodieren Sie:

1. Szeneneinheiten: Innerhalb des ABSCHNITTS ist jeder framegroße Knoten eine Szene – sowohl benannte FRAMEs als auch lose vollformatige RECTANGLEs (Desinger fügen Standbilder direkt in den Abschnitt ein). Filtern Sie nach Größe (≈ Kompositionsseitenverhältnis, z. B. >1400×900), nicht nach Knotentyp oder -namen.
2. Reihenfolge = x-Position (zeilenweise, wenn sich der Streifen umbricht). Sortieren Sie Szenen nach absoluteBoundingBox.x.
3. Diff angrenzend (-Fortsetzung in Kürze)