Plugin-Installation: Führen Sie vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln aus, wenn sich diese Fähigkeit innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die unten stehenden Aktualisierungshinweise.
Zunächst diese Fähigkeit aktuell halten – Bestätigung vom Benutzer einholen, bevor Sie ausführen:
npx hyperframes skills update figma. Ein schneller No-op, wenn alles auf dem neuesten Stand ist; andernfalls wird diese Fähigkeit sowie die wichtigsten Domain-Fähigkeiten, von denen sie abhängt, aktualisiert, bevor Sie darauf zurückgreifen.
Figma → HyperFrames
Die Figma-Arbeit des Benutzers in eine Komposition einbringen. Aufteilung 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, sofern verfügbar | Nutzung des Bewegungskontexts |
| 5 | Shader | Connector / manueller Export | Nutzung oder nativer Export |
REST wird überall dort verwendet, wo es möglich ist (nutzbar bei hohem Volumen, headless). Ein kompatibler Figma-Connector ist optional für Bewegungs- und Shaderdaten; falls keiner vorhanden ist, fordern Sie einen nativen Export an. Jeder Pfad friert Assets lokal ein, sodass Renderings deterministisch bleiben. Storyboard-Rekonstruktionen setzen Asset-Exporte der Phase 1 (REST) mit agentengesteuertem Timeline-Aufbau zusammen – kein Connector erforderlich. Vorhandene eingefrorene Assets, Manifest-Einträge und Bindungen werden von 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-Umgebungsvariable ([ -n "$FIGMA_TOKEN" ]) oder die Projekt-.env (die CLI lädt sie automatisch – ein .env-Eintrag gilt als konfiguriert). Wenn keines vorhanden ist, führen Sie NICHT den Befehl aus, um den Fehler abzufangen – führen Sie den Benutzer stattdessen zuerst durch die einmalige Einrichtung, stoppen Sie dann und warten Sie:
- 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. Fügen Sie Library content: Read-only hinzu, wenn Sie
tokensin einem Nicht-Enterprise-Tarif ausführen – der Fallback auf veröffentlichte Styles trifft/v1/files/:key/styles, was 403 ohne diesen Bereich zurückgibt (ein Bereich, den der ältere Setup-Text weggelassen hat). Optional Variables: Read-only für Markenvariablen – nur Enterprise; ohne ihn greifttokensautomatisch auf veröffentlichte Styles zurück (erwartet, kein Fehler – sagen Sie es). Ein 403 nennt jetzt den genau fehlenden Bereich; 429 werden automatisch wiederholt (Minutenlimit, ehrtRetry-After). - Lassen Sie den Benutzer
FIGMA_TOKENin seinem Shell-Profil oder der Projekt-.envsetzen; bitten Sie ihn niemals, den Token in die Konversation einzufügen.
Setzen Sie während des Onboardings auch in einem Satz die Erwartungen: Jeder Import landet als lokale eingefrorene Datei mit aufgezeichneter Herkunft – Renderings rufen niemals Figma auf, ein erneuter Befehl importiert nur das, was sich in Figma geändert hat, und ein Token funktioniert für Assets, Marken-Tokens und Komponenten in jeder 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, 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) mid-flow → der Token ist abgelaufen/widerrufen; neu ausstellen.FORBIDDEN(403) → die Nachricht nennt den genau fehlenden Bereich (z. B.library_content:readfür den Styles-Fallback) – fügen Sie ihn hinzu, oder die Datei ist für das Konto nicht sichtbar.REQUIRES_ENTERPRISE(403 auf Variablen) → kein Fehler: der Styles-Fallback wurde bereits ausgeführt.RATE_LIMITED(429) → der Client hat bereits mit Backoff wiederholt (dies gilt für JEDEN Lesevorgang – Assets, Tokens, Styles, Knotenbäume, Versionen – die Wiederholung lebt im gemeinsamen Request-Pfad;Retry-Afterwird eingehalten, 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-Tarif – 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 erfordert. REST ist pro Minute (10+/min, pro Endpunkt-Buckets) – bei hohem Volumen in Ordnung, bei 429 zurückziehen.
Routing
Den Figma-Link des Benutzers mit parseFigmaRef parsen (URL, fileKey:nodeId, reiner 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" → Component (CLI)
- "diese Animation / Bewegung importieren" → Motion (Connector, sofern verfügbar, siehe unten)
- einen Storyboard-Abschnitt / Filmstreifen von Szenen-Frames → Storyboard (siehe unten)
- Shader-Fülleffekt → Shaders (siehe unten)
Erzählen Sie jeden Schritt für den Benutzer – sagen Sie vor jedem Befehl, was Sie gleich aus Figma ziehen werden; sagen Sie danach, wo das Artefakt gelandet ist (der eingefrorene Pfad / Sidecar / Komponentenverzeichnis), 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 niemals fragen müssen "hat es funktioniert?" oder "was nun?".
Assets (Phase 1 – CLI)
hyperframes figma asset '<url-oder-fileKey:nodeId>' [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, 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. Immer --description "<was es ist>" übergeben (es wird zur Indexzeile + <img alt>); fügen Sie --entity "<name>" für benannte Markenzeichen hinzu, damit die Mediennutzung resolve --entity sie später findet (Entity-Treffer werden über Bild/Icon hinweg abgeglichen).
BATCHEN 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 Ratenlimit pro Minute ist – bevorzugen Sie es gegenüber N separaten Befehlen, wenn Sie die Assets eines ganzen Frames ziehen. --description/--entity gelten für jeden Knoten im Batch, also batchen Sie Knoten, die einen Zweck teilen. 429 werden ebenfalls automatisch mit Backoff wiederholt.
Tokens (Phase 2 – CLI)
hyperframes figma tokens <fileKey>
Importiert Variablen als Kompositions-Markenvariablen-Einträge + figma-tokens.json-Sidecar + Binding-Index-Einträge (.media/figma-bindings.jsonl). Variablen sind Enterprise-seitig gesperrt: In anderen Tarifen greift der Befehl auf Metadaten veröffentlichter Styles zurück (Werte werden zum Zeitpunkt des Komponentenimports aufgelöst). Fügen Sie die gedruckten Einträge in die data-composition-variables der Komposition ein.
Importieren Sie Tokens VOR Komponenten, wenn beide gewünscht sind – das ermöglicht es Komponentenfarben, sich mit Markenvariablen zu verknüpfen, anstatt Duplikate einzubacken.
Nicht-Enterprise-Variablen-Pfad (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 Binding-Index zu erstellen. Das boundVariables des REST-Knotenbaums 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 nachgelagert (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-Tarife 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 Neufärbung auffüllt, wenn sich der Variablenstandardwert ändert – das Aktualisieren eines Werts in data-composition-variables benennt jede importierte Komponente um, 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 in exakter Figma-Geometrie, verpackt als Registry-Element unter compositions/components/<name>/. Vektoren/boolesche Operationen werden automatisch über den Phasen-1-Export gerastert. Bindungspass (Spezifikation §7.1, nur exakte ID – niemals Wertabgleich):
- Statischer Fidelity-Selbsttest (obligatorisch für Hero-Inhalte): nach dem Importieren das Fragment rendern und mit Figmas eigenen Pixeln 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 beschnittene Grenzen (der Mapper emittierttext-box-trimdafür; gemessene Drift ohne war ~6px bei einer 70px-Schrift). Wenn der Vergleich eine Drift zeigt, die der Mapper nicht abdeckt, melden Sie sie – manipulieren Sie das Fragment nicht stillschweigend von Hand. - Füllung gebunden an einen importierten Token →
var(--slug, #literal)– Markenaktualisierung wird propagiert. - Gebunden an einen unbekannten Token → wörtlich +
data-figma-unresolved-Flag. Der Befehl teilt es Ihnen mit; bieten Sie dem Benutzer an: führen Sietokensauf der Quell- (oder Bibliotheks-) Datei aus, importieren Sie dann die Komponente neu, um sie zu verknüpfen. Fragen Sie einmalig pro unbekannter Bibliothek, um welche Datei es sich handelt – raten Sie nie, gleichen Sie nie nach Hex-Wert ab.
Bewegung (Phase 4 – Connector-gestützt)
Nutzungs-Bake: Connector-gestützte Phasen haben keinen CLI-Berührungspunkt, therefore das Skill-Bake zu Beginn und am Ende auslösen (anonym, zustimmungsabhängig, schlägt nie fehl): npx hyperframes events --skill=figma-motion beim Start, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error am Ende. Gleiches 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; fordern Sie andernfalls einen nativen Export an:
- Rufen Sie den Bewegungskontext für den übergeordneten Frame in einer rekursiven Anfrage ab, nicht eine Anfrage pro Element. Speichern Sie das rohe JSON neben dem Projekt (
.media/figma-cache/), sodass die Rückübersetzung kostenlos ist. - Normalisieren Sie in
MotionDocs mitmotionContextToDocs(rawResponse, { selectorFor, repeat })aus@hyperframes/core/figma– transkribieren Sie Keyframe-Nummern niemals von Hand. Der Helfer codiert die feldgetesteten Decodierungsregeln mechanisch: es parst die motion.dev-Schnipsel (die zuverlässige Codierung – die CSS-Schnipsel 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 denrepeat-Neustart realisiert) und bewahrt Bezier-Eases wörtlich auf.selectorFormuss die IDs aus dem Phasen-3-Komponentenimport zurückgeben – leiten Sie Selektoren nicht aus Knotennamen ab. 2b. Gegen Grundwahrheit validieren, bevor Sie es als erledigt bezeichnen – obligatorisch: Exportieren Sie den Root-Frame der Kohorte über den verfügbaren Connector und führen Sienode <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Yaus – es vergleicht Bewegung-Energie-Deltas (statische Importtreue hebt sich auf) und fällt unter 15 dB min Bewegung-PSNR (kalibriert: originalgetreu ≈ 20+, abweichend ≈ 5) durch. Messen Sie--cropvon den tatsächlichen Kartenkanten des Renderings, raten Sie nicht. FEHLER bedeutet, die Übersetzung zu überprüfen, nicht den Schwellenwert. motionToGsap(doc)→emitTimelineScript(spec)→ als<script>nach den GSAP- und CustomEase-CDN-Tags einfügen. Pausiert, endlich, aufwindow.__timelinesmit einem wörtlichen 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 reduziert Shader auf die Basisfarbe (siehe Shader unten), daher geht dort ein Bake stillschweigend den Shader verloren; fordern Sie stattdessen einen nativen Figma-Export vom Benutzer an. Sagen Sie immer, welchen Pfad Sie verwendet haben und warum. Benannte Eases außerhalb der zugeordneten Menge fallen auf linear zurück – die Zuordnungstabelle befindet sich inmotionEase.ts; kennzeichnen Sie den Fallback für den Benutzer, wenn er ausgelöst wird. - Führen Sie
npx hyperframes checkaus, bevor Sie es als erledigt bezeichnen.
Shader (Phase 5 – größtenteils manuell)
Figmas Connector-Rendering-Pfad führt keine Shader aus (sie werden auf die Basisfarbe reduziert), und Shader-Quellcode ist nur für bibliotheksveröffentlichte Styles (bezahlter Full Seat) erreichbar. Standardpfad: Bitten Sie den Benutzer, den Shader-Frame nativ in Figma zu exportieren (PNG oder Motion MP4) und dann als Phasen-1-Asset / Clip zu importieren. Versuchen Sie keine Connector-Pixel-Erfassung eines Shaders – sie wird stillschweigend das Falsche produzieren.
Storyboards (ein ABSCHNITT von Szenen-Frames → Animation)
Die kardinale 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 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 von ihnen implizierten Element-Zeitlinien ist die Aufgabe.
Storyboard-Dateien folgen einer Grammatik, die Sie mechanisch parsen können – schauen Sie nicht nach Augenmaß, decodieren Sie:
- Szeneneinheiten: innerhalb des ABSCHNITTs ist jeder frame-große Knoten eine Szene – sowohl benannte FRAMEs als auch lose ganzseitige RECTANGLEs (Designer fügen Standbilder direkt in den Abschnitt ein). Filtern Sie nach Größe (≈ Kompositionsseitenverhältnis, z. B. >1400×900), nicht nach Knotentyp oder -name.
- Reihenfolge = x-Position (zeilenweise, wenn der Streifen umbricht). Sortieren Sie Szenen nach
absoluteBoundingBox.x. - Diff benachbarter Szenen: subtrahieren Sie die keyframe-freie Ebene (Dekorationen, Hintergründe, Überlagerungen), die in aufeinanderfolgenden Szenen unverändert bleiben. Die Änderung ist der Bewegungssatz.
- Isobare Vermutung: wenn sich Inhalt zwischen Szene A und Szene B um den gleichen Vektor bewegt, ist es ein einzelnes sich bewegendes Element, nicht zwei unabhängige. Extrahieren Sie den Pfad, identifizieren Sie den Selektor (aus dem Phasen-3-Import), bauen Sie ein
MotionDoc. - Bewegungsauflösung (obligatorische Abschlussprüfung): Nachdem Sie die implizierten Zeitlinien rekonstruiert haben, führen Sie
npx hyperframes checkaus – es validiert, dass das Ergebnis der Szenenabfolge gleicht. Führen Sie danach den Bewegungsworkflow für Phase 4 aus (Schritte 2b–5 oben), als ob der Connector die Rohdaten bereitgestellt hätte, wobei SiemotionContextToDocsdurch die manuelleMotionDoc-Konstruktion ersetzen.
Das hier beschriebene Verfahren ersetzt jeden anderen Pfad für Storyboards – verwenden Sie es, wann immer der Benutzer einen Abschnitt szenenähnlicher Frames referenziert.
Aktualisierung und Status
- Aktualisieren Sie diese Fähigkeit, wann immer der Benutzer darum bittet oder wenn sich die Figma-Quelle ändert.
- Der Befehl
npx hyperframes skills update figmaaktualisiert die Fähigkeit. npx hyperframes checkvalidiert den aktuellen Zustand der Komposition und der Fähigkeit.