heygen-com/hyperframes

Plugin-Installationen: Befolgen Sie vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln, wenn sich dieses Skill innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die folgenden Update-Anweisungen.

Wichtig: Halten Sie dieses Skill aktuell – bestätigen Sie mit dem Benutzer vor der Ausführung: npx hyperframes skills update figma. Ein schneller No-op, wenn alles aktuell ist; andernfalls wird dieses Skill sowie die Kern-Domänen-Skills, von denen es abhängt, aktualisiert, bevor Sie darauf zurückgreifen.

Figma → HyperFrames

Übernehmen 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	ihn oder einen nativen Export verwenden

REST wird verwendet, wo immer möglich (nutzbar bei hohem Volumen, headless). Ein kompatibler Figma-Connector ist optional für Bewegungs- und Shader-Daten; ohne einen solchen fordern Sie einen nativen Export an. Jeder Pfad friert Assets lokal ein, sodass Renderings deterministisch bleiben. Storyboard-Rekonstruktionen kombinieren Phase-1-Asset-Exporte (REST) mit einer Agenten-gesteuerten Timeline-Erstellung – kein Connector erforderlich. Vorhandene eingefrorene Assets, Manifest-Datensätze und Bindungen werden durch Routing-Änderungen nicht beeinträchtigt – die Aufteilung ändert nur, welche Anmeldeinformationen der nächste Import verwendet.

Authentifizierung – zwei Anmeldeinformationen, abgestimmt

Preflight – vor dem ersten CLI-Aufruf prüfen, ob ein Token existiert: Shell-Umgebungsvariable ([ -n "$FIGMA_TOKEN" ]) oder die Projekt-.env-Datei (die CLI lädt sie automatisch – ein .env-Eintrag zählt als konfiguriert). Wenn keines vorhanden ist, führen Sie NICHT den Befehl aus, um den Fehler abzufangen – führen Sie den Benutzer stattdessen durch die einmalige Einrichtung und warten Sie dann:

1. figma.com/settings → Sicherheit → Persönliche Zugriffstoken → Neues Token generieren.
2. Bereiche – Nur-Lesen ist alles, was diese Integration jemals benötigt (sie schreibt nie in Figma): Dateiinhalt: Nur-Lesen + Dateimetadaten: Nur-Lesen. Fügen Sie Bibliotheksinhalt: Nur-Lesen hinzu, wenn Sie tokens in einem Nicht-Enterprise-Plan ausführen – der Fallback für veröffentlichte Styles greift auf /v1/files/:key/styles zu, was ohne diesen Bereich 403 zurückgibt (ein Bereich, der im älteren Setup-Text fehlte). Optional Variablen: Nur-Lesen für Markenvariablen – nur Enterprise; ohne ihn degradiert tokens automatisch zu veröffentlichten Styles (erwartet, kein Fehler – sagen Sie das). Ein 403 gibt jetzt den genauen fehlenden Bereich an; 429 werden automatisch wiederholt (Minutenlimit, respektiert Retry-After).
3. Lassen Sie den Benutzer FIGMA_TOKEN in seinem Shell-Profil oder der Projekt-.env-Datei setzen; bitten Sie ihn niemals, das Token in den Chat einzufügen.

Setzen Sie während des Onboardings auch in einem Atemzug die Erwartungen: Jeder Import landet als lokale eingefrorene Datei mit aufgezeichneter Herkunft – Renderings rufen nie 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 anzeigen 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 stoppen Sie dann.
• 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 erstellen. 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 bereits mit Backoff wiederholt (dies gilt für JEDES Lesen – Assets, Tokens, Styles, Knotenbäume, Versionen – die Wiederholung befindet sich im gemeinsamen Anforderungspfad; Retry-After wird respektiert, auf 60 s begrenzt); wenn es immer noch auftritt, warten Sie eine Minute oder importieren Sie weniger Knoten pro Aufruf.

Rate-Limit-Bewusstsein (Spezifikation §2.1): Connector-Kontingente variieren je nach Figma-Plan – bündeln Sie Parent-Frame-Anfragen, überspringen Sie Verifikations-Screenshots, sofern nicht danach gefragt, und cachen Sie rohe Antworten, sodass eine erneute Ableitung nie einen zweiten Aufruf erfordert. REST ist pro Minute (10+/min, pro-Endpunkt-Buckets) – bei hohem Volumen in Ordnung, bei 429 zurückfahren.

Routing

Parsen Sie den Figma-Link des Benutzers mit parseFigmaRef (URL, fileKey:nodeId, bare 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, unten)
• ein Storyboard-Abschnitt / Filmstreifen von Szenen-Frames → Storyboard (unten)
• Shader-Füllung/Effekt → Shader (unten)

Erzählen Sie jeden Schritt für den Benutzer – sagen Sie vor jedem Befehl, was Sie gleich aus Figma abrufen; sagen Sie danach, wo das Artefakt gelandet ist (der eingefrorene Pfad / Sidecar / Komponenten-Verzeichnis), was sich in der Komposition geändert hat und die unmittelbare nächste Aktion (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-or-fileKey:nodeId>' [weitere Referenzen…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

Wird per REST gerendert, bereinigt SVG, friert unter .media/images/ ein, hängt das Manifest mit Herkunft an, generiert .media/index.md (das gemeinsame Mediennutzungsinventar) neu und 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 Raster-Treue. Übergeben Sie immer --description "<was es ist>" (es wird zur Indexzeile + <img alt>); fügen Sie --entity "<Name>" für benannte Markenzeichen hinzu, damit media-use resolve --entity sie später findet (Entity-Treffer werden über Bild/Symbol hinweg erzielt).

Bündeln Sie viele Knoten in EINER Anfrage – übergeben Sie mehrere Referenzen (leerzeichen- oder kommagetrennt) der GLEICHEN 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 Rate-Limit pro Minute ist – bevorzugen Sie dies gegenüber N separaten Befehlen beim Abrufen der Assets eines gesamten Frames. --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 + Bindungsindex-Datensätze (.media/figma-bindings.jsonl). Variablen sind Enterprise-seitig gesperrt: bei anderen Plänen degradiert der Befehl zu veröffentlichten Styles-Metadaten (Werte werden zum Zeitpunkt des Komponentenimports aufgelöst). Fügen Sie die gedruckten Einträge zu den data-composition-variables der Komposition hinzu.

Importieren Sie Tokens vor Komponenten, wenn beide gewünscht sind – das ermöglicht es, dass Komponentenfarben mit Markenvariablen verknüpft werden, anstatt Duplikate einzubrennen.

Non-Enterprise Variables Path (feldgetestet): REST-Variablen sind Enterprise-seitig 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, um den Bindungsindex zu erstellen. Die boundVariables des REST-Knotenbaums liefern pro-Eigenschaft VariableIDs; verbinden 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 nachgelagert (Komponenten var()-Auflösung, Aktualisierung, Laufzeit-CSS-Variablen) ist die ausgelieferte Maschinerie. Kennzeichnen Sie 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 (Dokument-Root + Sub-Comp-Hosts), sodass importiertes var(--slug, literal) die Umfärbung auffüllt, wenn sich der Variablenstandardwert ä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-or-fileKey:nodeId>'

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. Bindungsdurchlauf (Spezifikation §7.1, nur exakte ID – niemals Wertabgleich):

• Statischer Treue-Selbstcheck (obligatorisch für Hero-Inhalte): Nach dem Importieren das Fragment rendern und mit Figmas eigenen Pixeln vergleichen – figma asset <gleicher Knoten> --format png ist die Grundwahrheit. Text ist die bekannte Abweichungsachse: ein Figma-Textfeld, das kürzer als seine Zeilenhöhe ist, hat vertikal abgeschnittene Begrenzungen (der Mapper gibt text-box-trim für diese aus; die gemessene Abweichung ohne war ~6px bei einer 70px-Schriftart). Wenn der Vergleich eine Abweichung zeigt, die der Mapper nicht abdeckt, melden Sie sie – passen Sie das Fragment nicht stillschweigend von Hand an.
• Füllung, die an ein importiertes Token gebunden ist → var(--slug, #literal) – Markenaktualisierung wird übernommen.
• Gebunden an ein unbekanntes Token → literal + data-figma-unresolved-Flag. Der Befehl teilt es Ihnen mit; bieten Sie dem Benutzer an: tokens auf der Quell- (oder Bibliotheks-) Datei ausführen, dann die Komponente erneut importieren, um sie zu verknüpfen. Fragen Sie einmal pro unbekannter Bibliothek, welche Datei es ist – niemals raten, niemals nach Hex-Wert abgleichen.

Bewegung (Phase 4 – Connector-unterstützt)

Nutzungs-Beacon: Connector-unterstützte Phasen haben keine CLI-Schnittstelle, also feuern Sie den Skill-Beacon zu Beginn und am Ende (anonym, zustimmungsbasiert, schlägt nie fehl): npx hyperframes events --skill=figma-motion wenn Sie beginnen, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error wenn Sie fertig sind. 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 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 eine erneute Übersetzung kostenlos ist.
2. Normalisieren Sie zu MotionDocs mit motionContextToDocs(rawResponse, { selectorFor, repeat }) aus @hyperframes/core/figma – transkribieren Sie Keyframe-Nummern niemals von Hand. Der Helfer kodiert die feldgetesteten Decodierungsregeln mechanisch: er parst die motion.dev-Snippets (die zuverlässige Kodierung – die CSS-Snippets dehnen Dauern und können widersprechen; sie werden ignoriert), entfernt Loop-Wrap-Tail-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-Easing-Verbatim. selectorFor muss die IDs aus dem Phase-3-Komponentenimport zurückgeben – leiten Sie Selektoren nicht von Knotennamen ab. 2b. Validieren Sie gegen die Grundwahrheit, bevor Sie es als erledigt bezeichnen – obligatorisch: Exportieren Sie den Root-Frame der Kohorte über den verfügbaren Connector und führen Sie node skills/figma/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) → als <script> nach den GSAP + CustomEase CDN-Tags einfügen. Pausiert, endlich, registriert auf window.__timelines mit einem literal-Schlüssel.
4. Nicht übersetzbarer Track (Shader-gesteuert, nicht unterstützte Eigenschaft, komplexe Masken) → durch den Connector exportieren, das MP4 einfrieren, dann als <video class="clip"> einbetten. Ausnahme: Shader-gesteuerte Tracks – Figmas Exportpfad flacht Shader auf die Basisfarbe ab (siehe Shader unten), also geht der Shader dort stillschweigend verloren; fordern Sie stattdessen einen nativen Figma-Export vom Benutzer an. Sagen Sie immer, welchen Pfad Sie verwendet haben und warum. Benannte Easings außerhalb des abgebildeten Satzes fallen auf linear zurück – die Zuordnungstabelle befindet sich 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 reduziert), und die Shader-Quelle ist nur für bibliotheksveröffentlichte Styles (kostenpflichtiger Full Seat) 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 nicht, einen Shader per Connector-Pixel-Erfassung zu erfassen – es wird stillschweigend das Falsche produzieren.

Storyboards (Ein ABSCHNITT von Szenen-Frames → Animation)

Die grundlegende Regel: Storyboard-Frames sind KEYFRAMES, keine Folien. Zwei Frames, die dasselbe Element enthalten, beschreiben den Zustand dieses Elements über die Zeit – animieren Sie das ELEMENT zwischen den Zuständen; spielen Sie die Frames niemals als eine Sequenz von Standbildern ab. Ein Logo, das in vier aufeinanderfolgenden Frames bei abnehmendem y gezeichnet wird, ist EIN Element, das durch vier Keyframes aufsteigt. Das Hintereinander-Abspielen von Storyboard-Frames ist der Fehlermodus; die Rekonstruktion der implizierten Element-Timelines ist die Aufgabe.

Storyboard-Dateien folgen einer Grammatik, die Sie mechanisch parsen können – nicht nach Augenmaß, decodieren Sie:

1. Szenen-Einheiten: Innerhalb des ABSCHNITTS ist jeder Frame-große Knoten eine Szene – sowohl benannte FRAMEs als auch lose Full-Frame-RECTANGLEs (Designer fügen Standbilder direkt in den Abschnitt ein). Filtern Sie nach Größe (≈ Kompositions-Seitenverhältnis, z. B. >1400×900), nicht nach Knotentyp oder -name.
2. Reihenfolge = x-Position (row-major, wenn sich der Streifen umbricht). Sortieren Sie Szenen nach absoluteBoundingBox.x.
3. Diff zwischen benachbarten Szenen (Szene₂ − Szene₁) enthüllt, welche Elemente sich bewegen, welche erscheinen/verschwinden und welche gleich bleiben. Ein Element, das in allen Szenen vorhanden ist, sich aber in der Position unterscheidet, ist eine Keyframe-Bewegung (Phase-1-Assets, die durch die Timeline-Kurve des Agenten verbunden sind). Ein Element, das in Szene₁ fehlt und in Szene₂ erscheint, ist ein Einblenden. Ein Element, das in Szene₁ vorhanden ist und in Szene₂ fehlt, ist ein Ausblenden. Reine Textänderungen (gleiche Position, anderer Text) sind ein Text-Cut (keine Animation – verwenden Sie textContent-Austausch zum Zeitpunkt des Schnitts).
4. Sobald Timeline-Segmente für jede Szene identifiziert sind, setzen Sie sie zu einer fortlaufenden Animation zusammen: scene[d] → ausblenden + scene[n+1] → einblenden mit überlappenden Übergängen. Verwenden Sie die results.storyboard.*-Helfer aus @hyperframes/core; schreiben Sie die Timeline nie von Hand.
5. Nach der Rekonstruktion führen Sie npx hyperframes check aus. Wenn die Ausgabe Abweichungen meldet (Standardabweichung der Keyframe-Positionen > 5px), passen Sie die transition-Dauer für dieses Segment an und wiederholen Sie die Überprüfung.

Geschwindigkeit beim ersten Gespräch: Ein Storyboard mit 20 Szenen kann die gesamte Konversation dominieren. Führen Sie die Decodierung, den Diff und die Timeline-Ausgabe in einem Hintergrundprozess durch und streamen Sie den Fortschritt (Szene 1/20 → berechnet, Szene 2/20 → berechnet…). Wenn der Benutzer die Nachricht sendet, bevor es fertig ist, halten Sie den Prozess an und geben Sie aus, was er hat – kündigen Sie die Abweichung an und fragen Sie, ob Sie die Animation mit dem vorliegenden Teilergebnis generieren sollen.