Wichtig: Halte dieses Skill aktuell – bestätige mit dem Nutzer, bevor du Folgendes ausführst:
npx hyperframes skills update figma. Ein schneller No-Op, wenn alles aktuell ist; andernfalls wird dieses Skill zusammen mit den abhängigen Kern-Skills aktualisiert, bevor du darauf vertraust.
Figma → HyperFrames
Bringe die Figma-Arbeit des Nutzers in eine Komposition ein. Aufgeteilt nach Fähigkeiten (Design-Spezifikation §2):
| Phase | Was | Transport | Oberfläche |
|---|---|---|---|
| 1 | Statische Assets | REST | hyperframes figma asset |
| 2 | Marken-Tokens/Stile | REST | hyperframes figma tokens |
| 3 | Komponenten → HTML | REST | hyperframes figma component |
| 4 | Bewegungen → GSAP | Connector (falls verfügbar) | Nutze seinen Bewegungskontext |
| 5 | Shader | Connector / manueller Export | Nutze ihn oder einen nativen Export |
REST wird verwendet, wo immer möglich (skalierbar, headless). Ein kompatibler Figma-Connector ist optional für Bewegungsdaten und Shader; ohne einen solchen fordere einen nativen Export an. Jeder Pfad friert Assets lokal ein, sodass Renderings deterministisch bleiben. Storyboard-Rekonstruktionen setzen Phase-1-Asset-Exporte (REST) mit agentengesteuerter Timeline-Erstellung 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, begrenzt
Vorbereitung – vor dem ersten CLI-Aufruf prüfe, ob ein Token existiert: Shell-Umgebung ([ -n "$FIGMA_TOKEN" ]) oder die Projekt-.env (die CLI lädt sie automatisch – ein .env-Eintrag zählt als konfiguriert). Wenn keines vorhanden ist, führe den Befehl NICHT aus, um den Fehler abzufangen – führe den Nutzer stattdessen durch die einmalige Einrichtung und warte dann:
- figma.com/settings → Security → Personal access tokens → Generiere einen neuen Token.
- Bereiche – Schreibgeschützt ist alles, was diese Integration jemals benötigt (sie schreibt nie in Figma): File content: Read-only + File metadata: Read-only. Füge Library content: Read-only hinzu, wenn du
tokensin einem Nicht-Enterprise-Plan ausführen wirst – der Fallback für veröffentlichte Stile greift auf/v1/files/:key/styleszu, was ohne diesen Bereich mit 403 quittiert wird (ein Bereich, den die ältere Setup-Anleitung ausgelassen hat). Optional Variables: Read-only für Markenvariablen – nur Enterprise; ohne diesen Bereich greifttokensautomatisch auf veröffentlichte Stile zurück (erwartet, kein Fehler – teile dies mit). Ein 403 nennt jetzt den genauen fehlenden Bereich; 429 werden automatisch wiederholt (Minutenlimit, beachtetRetry-After). - Lasse den Nutzer
FIGMA_TOKENin seinem Shell-Profil oder der Projekt-.envsetzen; bitte ihn niemals, den Token in die Unterhaltung einzufügen.
Setze während des Onboardings auch die Erwartungen in einem Atemzug: 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 aller Dateien, die das Figma-Konto des Nutzers einsehen kann.
- Phasen 4–5 (Bewegungen/Shader): ein kompatibler Figma-Connector mit separater Autorisierung vom Token. Wenn er nicht verfügbar oder nicht authentifiziert ist, bitte den Nutzer, ihn zu verbinden oder einen nativen Export bereitzustellen, und stoppe dann.
- Sage genau, welche Anmeldeinformationen eine fehlschlagende Phase benötigt – präsentiere die Aufteilung niemals als defekt.
BAD_TOKEN(401) während des Ablaufs → der Token ist abgelaufen/widerrufen; erstelle einen neuen.FORBIDDEN(403) → die Nachricht nennt den genauen fehlenden Bereich (z. B.library_content:readfü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: Stil-Fallback wurde bereits ausgeführt.RATE_LIMITED(429) → der Client hat bereits mit Backoff wiederholt (dies gilt für ALLE Lesevorgänge – Assets, Tokens, Stile, Knotenbäume, Versionen – die Wiederholung lebt im gemeinsamen Anforderungspfad;Retry-Afterwird beachtet, auf 60s gedeckelt); falls es dennoch auftaucht, warte eine Minute oder importiere weniger Knoten pro Aufruf.
Ratenbegrenzungsbewusstsein (Spezifikation §2.1): Connector-Kontingente variieren je nach Figma-Plan – gruppiere Eltern-Frame-Anfragen, überspringe Verifikations-Screenshots, falls nicht angefordert, und cache Rohantworten, sodass erneute Ableitungen nie einen zweiten Aufruf erfordern. REST ist pro Minute (10+/min, pro Endpunkt-Buckets) – funktioniert bei Volumen gut, reduziere bei 429.
Routing
Analysiere den Figma-Link des Nutzers mit parseFigmaRef (URL, fileKey:nodeId, bare fileKey). Dann nach Absicht:
- "Diese Ebene / dieses Logo / dieses Bild verwenden" → Asset (CLI)
- "Meine Marke / Farben / Tokens abrufen" → Tokens (CLI)
- "Eine Szene aus diesem Frame erstellen" → Component (CLI)
- "Diese Animation / Bewegung importieren" → Motion (Connector, falls verfügbar, siehe unten)
- Ein Storyboard-Abschnitt / Filmstreifen von Szenenframes → Storyboard (siehe unten)
- Shader-Füllung/-Effekt → Shaders (siehe unten)
Erzähle jeden Schritt für den Nutzer – sage vor jedem Befehl, was du gleich aus Figma abrufen wirst; danach, wo das Artefakt gelandet ist (der eingefrorene Pfad / Sidecar / Komponentenverzeichnis), was sich in der Komposition geändert hat, und den unmittelbaren nächsten Schritt (Vorschau, gedruckte Variablen hinzufügen, erneut importieren, um Bindungen zu verknüpfen). Der Nutzer sollte nie fragen müssen "Hat es funktioniert?" oder "Und 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 Mediennutzungsverzeichnis) und 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).
Gruppiere mehrere Knoten in EINER Anfrage – übergib mehrere Referenzen (durch Leerzeichen oder Komma getrennt) 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 Minutenratenlimit ist – bevorzuge dies gegenüber N separaten Befehlen beim Abrufen einer ganzen Frame-Ansammlung von Assets. --description/--entity gelten für jeden Knoten im Batch, also gruppiere Knoten, die einen gemeinsamen Zweck haben. 429 werden 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 eingeschränkt: Bei anderen Plänen fällt der Befehl auf published-style-Metadaten zurück (Werte werden beim Komponentenimport aufgelöst). Füge die gedruckten Einträge zur data-composition-variables der Komposition hinzu.
Importiere Tokens vor Komponenten, wenn beide gewünscht sind – das ermöglicht es Komponentenfarben, sich auf Markenvariablen zu beziehen, anstatt Duplikate zu erzeugen.
Nicht-Enterprise-Variablenpfad (feldgetestet): REST-Variablen sind Enterprise-seitig eingeschränkt, 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, cache die Rohantwort in .media/figma-cache/ und verwende sie, um den Bindungsindex zu erstellen. Das REST-Knotenbaum-boundVariables liefert VariableIDs pro Eigenschaft; verknüpfe sie nach Knoten und Eigenschaft und schreibe dann .media/figma-bindings.jsonl-Zeilen ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) plus die Kompositionsvariablen-Einträge. Alles Downstream (Komponenten-var()-Auflösung, Aktualisierung, Laufzeit-CSS-Variablen) ist die ausgelieferte Maschinerie. Kennzeichne es für den Nutzer: "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-Comp-Hosts), sodass importierte var(--slug, literal)-Füllungen die Umfärbung aktualisieren, wenn sich der Variablenstandard ändert – das Aktualisieren eines Werts in data-composition-variables brandet 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):
- Statische Treue-Selbstprüfung (obligatorisch für Heldeninhalte): nach dem Importieren rendere das Fragment und vergleiche es mit Figmas eigenen Pixeln –
figma asset <same node> --format pngist die Grundwahrheit. Text ist die bekannte Abweichungsachse: Ein Figma-Textfeld, das kürzer als seine Zeilenhöhe ist, hat vertikal abgeschnittene Grenzen (der Mapper gibttext-box-trimdafür aus; gemessene Abweichung ohne war ~6px bei einer 70px-Schrift). Wenn der Vergleich eine Abweichung zeigt, die der Mapper nicht abdeckt, melde sie – optimiere das Fragment nicht stillschweigend von Hand. - Füllung, die an einen importierten Token gebunden ist →
var(--slug, #literal)– Markenaktualisierung propagiert. - Gebunden an einen unbekannten Token → literal +
data-figma-unresolved-Flag. Der Befehl teilt es dir mit; biete dem Nutzer an: Führetokensauf der Quell-(oder Bibliotheks-)Datei aus und importiere dann die Komponente erneut, um sie zu verknüpfen. Frage einmal pro unbekannter Bibliothek, um welche Datei es sich handelt – rate niemals, gleiche niemals nach Hex-Wert ab.
Motion (Phase 4 – connector-unterstützt)
Nutzungsbeacon: Connector-unterstützte Phasen haben keinen CLI-Berührungspunkt, daher sende den Skill-Beacon zu Beginn und am Ende (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 wenn fertig. Gleiches für Shader (figma-shaders) und Storyboards (figma-storyboard).
Es gibt kein REST-Äquivalent. 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:
- Rufe den Bewegungskontext für den übergeordneten Frame in einer rekursiven Anfrage ab, nicht einer pro Element. Speichere das rohe JSON neben dem Projekt (
.media/figma-cache/), sodass die Neuübersetzung kostenlos ist. - Normalisiere in
MotionDocs mitmotionContextToDocs(rawResponse, { 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 widersprechen; 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 wörtlich.selectorFormuss die IDs aus dem Phase-3-Komponentenimport zurückgeben – leite Selektoren nicht von Knotennamen ab. 2b. Validiere gegen die Grundwahrheit, bevor du es als erledigt bezeichnest – obligatorisch: Exportiere den Wurzelrahmen der Kohorte über den verfügbaren Connector und führenode skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Yaus – es vergleicht Bewegungsenergie-Deltas (statische Importtreue hebt sich auf) und schlägt fehl unter 15 dB minimalem Bewegungs-PSNR (kalibriert: originalgetreu ≈ 20+, abweichend ≈ 5). Miss--cropvon den tatsächlichen Kartenkanten des Renderings, rate nicht. FEHLER bedeutet, die Übersetzung zu überprüfen, nicht den Schwellenwert. motionToGsap(doc)→emitTimelineScript(spec)→ füge als<script>nach den GSAP + CustomEase CDN-Tags ein. Pausiert, endlich, registriert aufwindow.__timelinesmit einem literal-Schlüssel.- Nicht übersetzbare Spur (shader-getrieben, nicht unterstützte Eigenschaft, komplexe Masken) → exportiere über den Connector, friere das MP4 ein und bette es als
<video class="clip">ein. Ausnahme: shader-getriebene Spuren – Figmas Exportpfad flacht Shader auf die Grundfarbe ab (siehe Shader unten), daher geht der Shader dort stillschweigend verloren; fordere den Nutzer stattdessen zu einem nativen Figma-Export auf. Sage immer, welchen Pfad du verwendet hast und warum. Benannte Eases außerhalb des abgebildeten Satzes fallen auf linear zurück – die Zuordnungstabelle lebt inmotionEase.ts; markiere den Fallback für den Nutzer, wenn er ausgelöst wird. - Führe
npx hyperframes checkaus, bevor du es als erledigt bezeichnest.
Shader (Phase 5 – meist manuell)
Figmas Connector-Renderpfad führt keine Shader aus (sie werden auf die Grundfarbe abgeflacht), und Shader-Quellcode ist nur für bibliotheksveröffentlichte Stile (kostenpflichtiger Vollzugang) erreichbar. Standardpfad: Fordere den Nutzer auf, den Shader-Frame nativ in Figma zu exportieren (PNG oder Motion-MP4) und dann als Phase-1-Asset/Clip zu importieren. Versuche keine Connector-Pixel-Erfassung eines Shaders – sie wird stillschweigend das Falsche liefern.
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 eine 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 die Fehlerart; die Element-Timelines, die sie implizieren, zu rekonstruieren, ist die Aufgabe.
Storyboard-Dateien folgen einer Grammatik, die du mechanisch parsen kannst – schätze nicht, dekoriere:
- Szeneneinheiten: Innerhalb des ABSCHNITTS ist jeder frame-große Knoten eine Szene – sowohl benannte FRAMEs als auch lose vollbildgroße 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.
- Reihenfolge = x-Position (zeilenweise, wenn der Streifen umbricht). Sortiere Szenen nach
absoluteBoundingBox.x. - Diff benachbarter Frames in Elementketten – hier lebt die Animation. Gleiche untergeordnete Elemente ü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 + Position → wahrscheinlich dasselbe Element, selbst wenn der Name wechselt). Erstelle für jede Kette einen
AnimationDocmit Start-End-Paaren. - Szenenübergreifendes Element-Matching: Ein Element, das in mehreren Szenen vorkommt, ist ein animiertes Element über eine Szenengrenze hinweg. Erstelle eine übergeordnete Timeline, die die Szene-Subtimelines enthält.
- Gib die
MotionDocs aus (eines pro Elementkette).
Erstelle und injiziere niemals eine statische Diashow – das ist der häufigste Fehler. Wenn nach dem Parsen keine Bewegung entsteht (alle Frames sind identisch), informiere den Nutzer und biete an, stattdessen als statischen Frame zu importieren.
Szenen-Wiederholungen erkennen: Wenn zwei aufeinanderfolgende Frames identische Kinder an identischen Positionen haben, überspringe den zweiten und fahre mit dem dritten fort. Informiere den Nutzer: "Frame X übersprungen – keine Änderung gegenüber Frame Y."
Fehler, die du nicht stillschweigend beheben sollst
| Problem | Erwartete Reaktion |
|---|---|
| Abgeschnittener Text (siehe Statische Treue-Selbstprüfung oben) | Melde die Abweichung; biete an, die Zeilenhöhe oder den Container im Figma-Editor anzupassen |
| ÜBERLAPPENDER Text / falsche Ebenen-Reihenfolge | Frage den Nutzer, ob er die Ebenen in Figma neu anordnen möchte, oder ob die aktuelle Reihenfolge beabsichtigt ist |
| Fehlende Schriftarten (Fallback auf systemweit) | "Dieses Design verwendet [Schriftarten], die nicht auf diesem System verfügbar sind. Fallback auf systemweit: [Liste]." Frage den Nutzer, ob er fortfahren oder zuerst Schriften installieren möchte (empfohlen: Aussetzer erwartet) |
| SVG-Sicherheitsproblem (XSS-Versuch in exportiertem SVG) | Breche ab; informiere den Nutzer; biete an, als PNG zu exportieren |
| Ungültiger Figma-Link (kann nicht analysiert werden, Datei nicht vorhanden, keine Berechtigung) | Sage dem Nutzer, was am Link falsch ist; schlage vor, den Link in Figma zu öffnen und zu kopieren |
| Connector nicht verfügbar für Phase 4/5 | "Phase 4 (Bewegung) erfordert einen kompatiblen Figma-Connector. Bitte verbinde einen oder exportiere die Bewegung als MP4 aus Figma." Sage genau, was fehlt |
| Komponente wird außerhalb der Komposition aktualisiert | "Die importierte Komponente spiegelt Figma nicht mehr vollständig wider. Möchtest du sie neu importieren? Das wird lokale Optimierungen überschreiben." |
gitzone / Konvention
- Jeder Import erzeugt eine eingefrorene Mediendatei + einen Herkunftseintrag im Manifest.
- Führe
npx hyperframes checkaus, bevor du als erledigt meldest – es validiert die Kompositionsstruktur, fehlende Bindungen und hängende Verweise. - Erstelle keine Branches, Tags oder Commits – das ist die Aufgabe des Nutzers.
- Wenn der Nutzer nach einem Playground/Sandbox fragt:
compositions/playground/figma-import/<date>. - Protokolliere die Anzahl der importierten Elemente, den Speicherort der Ausgabe, die Bindungsstatistiken und die Datenherkunft.
- Bestätige, dass der Nutzer die Änderungen überprüfen kann, indem er
npx hyperframes serveausführt.
npx hyperframes CLI-Referenz
npx hyperframes figma asset '<url-or-fileKey:nodeId>' [--format svg|png|jpg|pdf] [--scale 1|2|3|4] [--description "..."] [--entity "..."]
npx hyperframes figma tokens <fileKey>
npx hyperframes figma component '<url-or-fileKey:nodeId>'
npx hyperframes check
npx hyperframes serve
npx hyperframes render [--variables '<json>']
npx hyperframes skills update figma
npx hyperframes events --skill=figma-motion [--event=...] [--outcome=...]