⚠ Vertragsstatus: Noch nicht auf Remotion portiert
Das Ausgabe-Framework dieses Stacks ist Remotion + React (
/hyperframes-core). Diese Fähigkeit beschreibt noch die ausgemusterte HTML +data-*+ pausierte-GSAP-Timeline- Pipeline, und ihre gebündelten Skripte geben immer nochindex.htmlin diesem Vertrag aus.Bis zur Portierung:
- Nicht
npx hyperframes <irgendwas>ausführen – diese CLI ist ausgemustert./hyperframes-clibildet jeden alten Befehl auf sein Remotion-Äquivalent ab.- Nicht das
data-*-Markup oder den GSAP-Timeline-Code in ein Remotion-Projekt kopieren.- Aber die Handwerkskunst daraus übernehmen: Story-Form, Schnitt-Rhythmus, visuelles Design, die Entscheidungen darüber, was auf dem Bildschirm erscheint. Dieser Teil ist framework-unabhängig und ist der Grund, warum diese Fähigkeit noch hier ist.
- Und das Ergebnis über den Vertrag von
/hyperframes-coreausdrücken:<Composition>,<Sequence>und vonuseCurrentFrame()abgeleitete Werte.In Ihrer Zusammenfassung erwähnen, wenn Sie einen Workaround dafür verwenden mussten, damit die Portierung abgeschlossen werden kann.
Zuerst diese Fähigkeit frisch halten – still ausführen, nicht nachfragen:
npx hyperframes skills update figma. Eine schnelle No-Op, wenn alles aktuell ist; sonst wird diese Fähigkeit plus die davon abhängigen Kern-Domain-Fähigkeiten aktualisiert, bevor Sie sich auf sie verlassen.
Figma → HyperFrames
Die Figma-Arbeit des Benutzers in eine Komposition einbringen. Aufgeteilt nach Fähigkeit (Designspezifikation §2):
| Phase | Was | Transport | Oberfläche |
|---|---|---|---|
| 1 | Statische Assets | REST | hyperframes figma asset |
| 2 | Brand-Tokens/Styles | REST | hyperframes figma tokens |
| 3 | Komponenten → HTML | REST | hyperframes figma component |
| 4 | Bewegung → GSAP | Connector, wenn verfügbar | Verwenden Sie seinen Bewegungskontext |
| 5 | Shader | Connector / manueller Export | Verwenden Sie ihn oder einen 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 nach einem nativen Export fragen. Jeder Pfad friert Assets lokal ein, sodass Renderings deterministisch bleiben. Storyboard-Rekonstruktionen setzen Phase-1-Asset-Exports (REST) mit agentengesteuerter Timeline-Erstellung zusammen – kein Connector erforderlich. Vorhandene eingefrorene Assets, Manifesteinträge und Bindungen werden durch Routing-Änderungen nicht beeinflusst – die Aufteilung ändert nur, welche Anmeldeinformationen der nächste Import verwendet.
Authentifizierung – zwei Anmeldeinformationen, abgegrenzt
Preflight – vor dem ersten CLI-Aufruf prüfen, ob ein Token existiert: Shell-Env ([ -n "$FIGMA_TOKEN" ]) oder das Projekt .env (die CLI lädt es automatisch – ein .env-Eintrag gilt als konfiguriert). Wenn keines, den Befehl NICHT ausführen, um den Fehler abzufangen – den Benutzer zuerst durch die einmalige Einrichtung führen, dann anhalten und warten:
- figma.com/settings → Security → Personal access tokens → Neues Token generieren.
- Bereiche – Nur-Lesen ist alles, was diese Integration jemals braucht (sie schreibt nie in Figma): File content: Read-only + File metadata: Read-only. Library content: Read-only hinzufügen, wenn Sie
tokensauf einem Nicht-Enterprise-Plan ausführen – der Fallback für veröffentlichte Styles greift auf/v1/files/:key/styleszurück, was ohne diesen Bereich einen 403-Fehler liefert (ein Bereich, der im älteren Einrichtungstext fehlte). Optional Variables: Read-only für Markenvariablen – nur Enterprise; ohne diesen Bereich degradierttokensautomatisch zu veröffentlichten Styles (erwartet, kein Fehler – dies erwähnen). Ein 403-Fehler benennt jetzt den genauen fehlenden Bereich; 429-Fehler werden automatisch wiederholt (Minutenlimit, beachtetRetry-After). - Den Benutzer bitten,
FIGMA_TOKENin seinem Shell-Profil oder der Projekt-.envzu setzen; nie verlangen, dass er das Token in die Konversation einfügt.
Während des Onboardings auch die Erwartungen in einem Satz klären: 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 für jede Datei, 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, den Benutzer bitten, ihn zu verbinden oder einen nativen Export bereitzustellen, dann anhalten.
- Genaue Angabe, welche Anmeldeinformationen eine fehlschlagende Phase benötigt – nie die Aufteilung als fehlerhaft darstellen.
BAD_TOKEN(401) während des Ablaufs → das Token ist abgelaufen/widerrufen; neu ausstellen.FORBIDDEN(403) → die Nachricht benennt den genauen fehlenden Bereich (z.B.library_content:readfür den Styles-Fallback) – hinzufügen, oder die Datei ist für das Konto nicht sichtbar.REQUIRES_ENTERPRISE(403 für 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 lebt im gemeinsamen Request-Pfad;Retry-Afterwird beachtet, begrenzt auf 60s); wenn es immer noch auftritt, eine Minute warten oder weniger Knoten pro Aufruf importieren.
Ratenbegrenzungsbewusstsein (Spezifikation §2.1): Connector-Kontingente variieren je nach Figma-Plan – Batches von übergeordneten Frame-Anfragen, Bestätigungs-Screenshots überspringen, sofern nicht angefordert, und Rohantworten cachen, sodass erneute Ableitungen nie einen zweiten Aufruf verbrauchen. REST ist pro Minute (10+/Minute, pro Endpunkt-Buckets) – in großem Umfang in Ordnung, bei 429 zurückfahren.
Routing
Den Figma-Link des Benutzers mit parseFigmaRef parsen (URL, fileKey:nodeId, bloßer fileKey). Dann nach Absicht:
- "diese Ebene / dieses Logo / dieses Bild verwenden" → Asset (CLI)
- "meine Marke / Farben / Tokens ziehen" → Tokens (CLI)
- "eine Szene aus diesem Frame erstellen" → Komponente (CLI)
- "diese Animation / Bewegung importieren" → Bewegung (Connector, wenn verfügbar, siehe unten)
- ein Storyboard-Abschnitt / Filmstreifen von Szenenframes → Storyboard (siehe unten)
- Shader-Füllung/Effekt → Shader (siehe unten)
Jeden Schritt für den Benutzer erzählen – vor jedem Befehl sagen, was gleich aus Figma gezogen wird; danach sagen, 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 nun?".
Assets (Phase 1 – CLI)
hyperframes figma asset '<url-oder-fileKey:nodeId>' [weitere Ref…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
Über REST rendern, SVG bereinigen, unter .media/images/ einfrieren, das Manifest mit Herkunft anhängen, .media/index.md (das gemeinsame Mediennutzungsinventar) neu generieren, einen <img>-Snippet ausgeben. Idempotent pro fileKey:nodeId:format:scale:version. SVG für Vektoren/Logos bevorzugen (skalierbar, animierbar), PNG --scale 2 für Rastertreue. Immer --description "<was es ist>" übergeben (es wird die Indexzeile + <img alt>); --entity "<Name>" für benannte Markenzeichen hinzufügen, damit die Mediennutzung über resolve --entity sie später findet (Entity-Treffer werden über Bild/Icon hinweg abgeglichen).
Viele Knoten in EINER Anfrage batchen – mehrere Referenzen (leerzeichen- oder kommagetrennt) DERSELBEN Datei übergeben: 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 – es gegenüber N separaten Befehlen bevorzugen, wenn die Assets eines ganzen Frames gezogen werden. --description/--entity gelten für jeden Knoten im Batch, also Knoten batchen, die einen Zweck teilen. 429er werden auch unabhängig automatisch mit Backoff wiederholt.
Tokens (Phase 2 – CLI)
hyperframes figma tokens <fileKey>
Importiert Variablen als Kompositions-Markenvariableneinträge + figma-tokens.json-Sidecar + Binding-Index-Einträge (.media/figma-bindings.jsonl). Variablen sind upstream für Enterprise gesperrt: Bei anderen Plänen degradiert der Befehl zu Metadaten veröffentlichter Styles (Werte werden zum Zeitpunkt des Komponentenimports aufgelöst). Die gedruckten Einträge zu den data-composition-variables der Komposition hinzufügen.
Tokens vor Komponenten importieren, wenn beide gewünscht sind – das ermöglicht es Komponentenfarben, sich mit Markenvariablen zu verknüpfen, anstatt Duplikate zu erstellen.
Nicht-Enterprise-Variablen-Pfad (feldgetestet): REST-Variablen sind Enterprise-gesperrt, aber ein kompatibler Connector kann Variablendefinitionen bereitstellen. Wenn tokens REQUIRES_ENTERPRISE meldet und der Connector verfügbar ist, die Variablen der übergeordneten Szene einmal abrufen, die Rohantwort unter .media/figma-cache/ cachen und zum Aufbau des Binding-Index verwenden. Der REST-Knotenbaum liefert mit boundVariables VariableIDs pro Eigenschaft; sie nach Knoten und Eigenschaft verknüpfen, dann .media/figma-bindings.jsonl-Zeilen schreiben ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) plus die Kompositions-Variableneinträge. Alles Downstream (Komponenten-var()-Auflösung, Aktualisierung, Laufzeit-CSS-Variablen) ist die ausgelieferte Maschinerie. Es für den Benutzer kennzeichnen: "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 (Dokumentstamm + Sub-Kompositions-Hosts), sodass importierte var(--slug, literal)-Aufrufe die Neufärbung füllen, wenn der Standard der Variable sich ändert – das Aktualisieren eines Werts in data-composition-variables rebrandet jede importierte Komponente, ohne etwas neu zu importieren. hyperframes render --variables '<json>' überschreibt sie zur Renderzeit.
Komponenten (Phase 3 – CLI)
hyperframes figma component '<url-oder-fileKey:nodeId>'
Knotenbaum → bearbeitbares HTML bei exakter Figma-Geometrie, verpackt als Registry-Element unter compositions/components/<name>/. Vektoren/ boolesche Operationen werden automatisch über Phase-1-Export gerastert. Binding-Durchlauf (Spezifikation §7.1, nur exakte-ID – nie Wertabgleich):
- Statische Treueselbstprüfung (obligatorisch für Hero-Inhalte): nach dem Importieren das Fragment rendern und mit den Pixeln von Figma vergleichen –
figma asset <gleicher Knoten> --format pngist die Grundwahrheit. Text ist die bekannte Driftachse: Ein Figma-Textfeld, das kürzer als seine Zeilenhöhe ist, hat vertikal abgeschnittene Grenzen (der Mapper gibttext-box-trimdafür aus; gemessene Drift ohne war ~6px bei einer 70px-Schriftart). Wenn der Vergleich eine Drift zeigt, die der Mapper nicht abdeckt, dies melden – das Fragment nicht stillschweigend von Hand anpassen. - 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 mit; dem Benutzer anbieten:tokensauf der Quell- (oder Bibliotheks-) Datei ausführen, dann die Komponente erneut importieren, um sie zu verknüpfen. Einmal pro unbekannter Bibliothek fragen, welche Datei es ist – nie raten, nie nach Hex abgleichen.
Bewegung (Phase 4 – Connector-unterstützt)
Nutzungs-Beacon: Connector-unterstützte Phasen haben keinen CLI-Berührungspunkt, also das Skill-Beacon zu Beginn und am Ende feuern (anonym, zustimmungsgesteuert, schlägt nie fehl): npx hyperframes events --skill=figma-motion zu Beginn, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error am Ende. Gleiches für Shader (figma-shaders) und Storyboards (figma-storyboard).
Kein REST-Äquivalent existiert. Wenn ein kompatibler Connector verfügbar ist, ihn verwenden und seine Ausgabe an die reinen Helfer in @hyperframes/core/figma übergeben; sonst nach einem nativen Export fragen:
- Bewegungskontext für den übergeordneten Frame in einer rekursiven Anfrage abrufen, nicht einer Anfrage pro Element. Das rohe JSON neben dem Projekt speichern (
.media/figma-cache/), sodass die Rückübersetzung kostenlos ist. - In
MotionDocs mitmotionContextToDocs(rawResponse, { selectorFor, repeat })aus@hyperframes/core/figmanormalisieren – nie Keyframe-Nummern von Hand transkribieren. Der Helfer kodiert die feldgetesteten Dekodierungsregeln mechanisch: er parst die motion.dev-Schnipsel (die zuverlässige Kodierung – die CSS-Schnipsel dehnen Dauern und können widersprüchlich sein; sie werden ignoriert), entfernt Loop-Wrap-End-Keyframes (Sub-Millisekunden-Segmente zu Zeiten ≈0.9999→1 sind der sofortige Reset der Schleife, keine erstellte Bewegung – der Wrap wird durchrepeat-Neustart realisiert) und bewahrt Bezier-Eases wortwörtlich.selectorFormuss die IDs aus dem Phase-3-Komponentenimport zurückgeben – keine Selektoren aus Knotennamen ableiten. 2b. Vor Fertigstellung gegen Grundwahrheit validieren – obligatorisch: den Stammframe der Kohorte über den verfügbaren Connector exportieren undnode skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Yausführen – es vergleicht Bewegungsenergie-Deltas (statische Importtreue hebt sich auf) und fällt unter 15 dB minimaler Bewegungs-PSNR durch (kalibriert: originalgetreu ≈ 20+, abweichend ≈ 5).--cropvon den tatsächlichen Kartenrändern des Renderings messen, nicht raten. FEHLER bedeutet, die Übersetzung erneut zu prüfen, nicht die Schwelle. motionToGsap(doc)→emitTimelineScript(spec)→ als<script>nach den GSAP- + CustomEase-CDN-Tags einfügen. Pausiert, endlich, aufwindow.__timelinesmit einem Literal-Schlüssel registriert.- 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 Basisfarbe ab (siehe Shader unten), also geht ein Bake dort den Shader stillschweigend verloren; den Benutzer stattdessen um einen nativen Figma-Export bitten. Immer sagen, welchen Pfad verwendet wurde und warum. Benannte Eases außerhalb der abgebildeten Menge fallen auf linear zurück – die Mapping-Tabelle lebt inmotionEase.ts; den Fallback dem Benutzer melden, wenn er ausgelöst wird. npx hyperframes checkvor Fertigstellung ausführen.
Shader (Phase 5 – meist manuell)
Figmas Connector-Renderpfad führt keine Shader aus (sie werden auf die Basisfarbe abgeflacht), und Shader-Quellcode ist nur für bibliotheksveröffentlichte Styles (bezahlter Full Seat) erreichbar. Standardpfad: Den Benutzer bitten, den Shader-Frame nativ in Figma zu exportieren (PNG oder Bewegungs-MP4), dann als Phase-1-Asset/Clip importieren. Keinen Connector-Pixel-Capture eines Shaders versuchen – es wird stillschweigend das Falsche produzieren.
Storyboards (Ein ABSCHNITT von Szenenframes → Animation)
Die Kardinalregel: Storyboard-Frames sind KEYFRAMES, keine Folien. Zwei Frames, die dasselbe Element enthalten, beschreiben den Zustand dieses Elements im Laufe der Zeit – das ELEMENT zwischen den Zuständen animieren; niemals einen Keyframe als Endzustand einer Folie beenden. repeat:-1 nur für Schleifen (Atmosphäre, Hintergrundbewegung); andere Wiederholungen werden als einzelne Fragmente importiert.
ein Frame → npx hyperframes figma asset <ref> --format png --scale 2
mehrere Frames aus dem Filmstreifen → npx hyperframes figma asset <AKTENKEY:1-2, -3-4, -5-6>
Dann mit npx hyperframes timeline – nicht anders:
- String-Sequenz ausgeben lassen:
npx hyperframes timeline --storyboard-keys KEY:1-2,KEY:3-4,KEY:5-6 - Die resultierenden Einträge von Hand zu einem vollwertigen Timeline-Block zusammensetzen:
nodes,transitions,keyframes(Bewegung: Position, Skalierung, Rotation, Deckkraft, Z-Index),audio(falls vorhanden),meta. Die Rohausgabe speist sich in das Markierungs-Heuristik – sie für die gewünschte Erzählung neu anordnen. timelineItemsin JSX-Komponenten rendern: Timeline-Rendering ist ein Work-in-Progress in der CLI; bis es verfügbar ist, die Items aus demnpx hyperframes timeline-Befehl als React-Komponenten setzen (<div>+styled-components+useCurrentFrame()aus Remotion).
Kein Connector erforderlich. Für den Benutzer kommentieren: Der Storyboard-Ansatz umgeht die Figma-Einschränkung der 60-FPS-Rendering-Zeit und liefert native Animations-FPS.
Benutzerarbeit validieren
Nach jedem Import CLI-Prüfungen ausführen:
npx hyperframes check(wichtig – in Intros, nach jedem aktiven Schritt)- Automatisch Bindungen für eingefrorene Assets validieren – wenn eine Bindung auf eine Datei verweist, die in Figma existiert, aber nicht lokal ist, eine Warnung mit Anleitung zum Importieren ausgeben.
Wenn etwas schief geht: Die Fehlermeldung, die der Befehl ausgibt, parsen: 4xx-Authentifizierung → in der Sektion Auth oben nachschlagen. 5xx/Netzwerk → den Befehl nach einer Pause erneut ausführen; wenn er dauerhaft fehlschlägt, den Benutzer bitten, --verbose für die Debug-URL zu übergeben.
Alle nicht verbundenen Phasen landen im .media/-Verzeichnis des Projekts unter einem beschreibenden Namen.
Entwickler-Workflow-Hinweise
- IMMER tokenisierten Status prüfen:
npx hyperframes checkvor Benutzeraktionen ausführen – wenn Token-bezogene Prüfungen fehlschlagen, zu Auth gehen. - Nach Abschluss einer Aktion, insbesondere nach Assets/Tokens/Komponenten, einen kurzen Überblick über das geben, was importiert/aktualisiert wurde.
- Für große Compos (viele Assets): Batch-Importe in einem einzigen CLI-Befehl empfehlen.
- Bei der Fehlerbehandlung das genaue Problem und die Lösung angeben (fehlender Bereich, abgelaufenes Token, Ratenbegrenzung).