use_figma – Figma Plugin API Skill für Motion
Motion-Kontext für das use_figma MCP-Tool. figma-use behandelt die grundlegenden Plugin-API-Regeln – beide zusammen laden.
Immer skillNames: "figma-use-motion" (kommagetrennt zusammen mit figma-use) übergeben, wenn use_figma für Bewegungsarbeit aufgerufen wird. Nur zum Loggen.
Runtime-Gating
Motion-APIs sind hinter dem Benutzer-Feature-Flag metronome geschützt. Wenn der aufrufende Benutzer es nicht hat, wirft jede in diesem Skill referenzierte Motion-Eigenschaft und -Hilfsfunktion den Fehler "<name>" is not a supported API.
Bei diesem Fehler schnell aussteigen. Nicht wiederholen; dem Benutzer mitteilen, dass Motion für ihn nicht aktiviert ist, und abbrechen. Andernfalls werden Aufrufe verschwendet und der Benutzer durch wiederholte identische Fehler verwirrt.
Wann diese Skill verwenden
Diese Skill laden, wenn eine use_figma-Aufgabe Folgendes umfasst:
- Hinzufügen, Bearbeiten oder Entfernen von Keyframes auf einem Knoten (
manualKeyframeTracks,applyManualKeyframeTrack,removeManualKeyframeTrack). - Animieren von Füll- oder Strichfarben über die Zeit.
- Anwenden, Bearbeiten oder Entfernen von Animationsstilen (
applyAnimationStyle,removeAnimationStyle,animationStyles). - Lesen oder Schreiben der Zeitliniendauer über
node.timelines/node.setTimelineDuration(id, seconds). - Auswählen von Easing für eine der oben genannten Aktionen.
Statische Designarbeit (Erstellen von Formen, Komponenten, Variablen, Layout) erfolgt allein über figma-use – diese Skill ist nur für die Zeitdimension.
Freigegebene Motion-API-Oberfläche
node.manualKeyframeTracks– manuelle Keyframes lesen/schreiben (einschließlich Füll-, Strich- und Effekt-Tracks).node.applyManualKeyframeTrack(field, track)/node.removeManualKeyframeTrack(field)– einen manuellen Keyframe-Track hinzufügen, ersetzen oder entfernen, ohne das gesamte Objekt neu zu schreiben.node.animationStyles– auf einen Knoten angewendete Animationsstil-Metadaten lesen/schreiben.node.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)– einen entdeckten Stil anwenden und eine angewendete Stilinstanz anhand ihrer zurückgegebenen/zurückgelesenenidentfernen.node.timelines– schreibgeschützte Zeitlinienliste für den enthaltenden obersten Frame mit Dauern in Sekunden.node.setTimelineDuration(id, durationSeconds)– die Zeitliniendauer des enthaltenden obersten Frames schreiben.node.animations– schreibgeschützte aufgelöste Keyframe-Daten (derzeit nur manuelle Tracks – siehe motion-patterns.md).figma.motion.figmaAnimationStyles()– schreibgeschützte Liste der erstklassigen Animationsstile von Figma.
Das Erstellen benutzerdefinierter Quellcode für "figma:motion"-Preset-Module liegt außerhalb des Rahmens. Wenn der Benutzer einen brandneuen Animationsstil wünscht, dies mitteilen und abbrechen; keinen erfinden.
Referenzdokumente
Diese je nach Aufgabenbereich nach Bedarf laden:
| Dokument | Wann laden | Was es abdeckt |
|---|---|---|
| motion-patterns.md | Hinzufügen/Bearbeiten von Bewegungsanimationen | Manuelle Keyframes, animierte Füllungen/Striche, Anwenden von Animationsstilen, Zeitliniendauer |
| motion-easing.md | Einstellen des Animations-Easings | Keyframe-Easing-Objekte, benutzerdefiniertes Cubic/Spring, HOLD, Anwenden von Easing innerhalb eines Animationsstils |
Überprüfen der Animation
get_screenshot zeigt nur den Ruhezustand der Zeitleiste, niemals Bewegung. Zur Überprüfung der Bewegung export_video verwenden und Einzelbilder entnehmen – dies rendert jedoch serverseitig und ist langsam und teuer (~10 s bis Minuten). Daher jedes Rendern sinnvoll nutzen.
Vor dem Rendern planen – die Kosten skalieren mit Pixel × Frames, also beide nicht größer als nötig halten:
- Zuerst die Momente auswählen. Es wird ein Frame pro Phase benötigt (z. B. pro Staffelungsschritt oder Start / Mitte / Ende), nicht flüssige Wiedergabe – normalerweise 4–6. Diese Anzahl bestimmt die fps.
- **Auf das Nötigste verkleinern Klein anfangen –
constraint: { type: 'WIDTH', value: 320 },quality: "low"– aber Text und kleine Elemente werden dort unscharf, alsoWIDTH(768+) erhöhen, wenn feine Details zu beurteilen sind.constraintweglassen = volle Größe (1x; Server begrenzt auf 10x / 4096 Pixel). - Fps gerade so hoch einstellen, dass diese Frames erreicht werden:
fps: 5deckt eine Handvoll ab; 10 ist eine Obergrenze. Höhere Werte blähen das Rendern nur auf.
Mechanik: export_video funktioniert nur auf einem obersten Frame, dessen Kinder die Animation tragen (diesen Frame übergeben, nicht den Nachkommen, der mit Keyframes versehen wurde). Es gibt eine jobId mit status: "processing" zurück – erneut mit { fileKey, jobId } aufrufen, um abzufragen. Anschließend lokal mit ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png Einzelbilder extrahieren – Extraktion ist kostenlos. Sobald das Rendern bezahlt ist, jeden Frame ausnutzen, der etwas aussagt, anstatt erneut zu exportieren. Ohne einen Frameextraktor wie ffmpeg den Export überspringen und stattdessen die Keyframes analysieren.
Iterieren, bis es stimmt. Der Export ist eine Diagnose, keine Freigabe: Wenn die Frames falsch sind (falsche Reihenfolge, falsches Timing, fehlendes Element, eine Maske, die die Komposition ausblendet), die Keyframes/Style korrigieren und erneut exportieren. Alle Frames lesen und jede Korrektur in einem Durchgang bündeln, bevor erneut gerendert wird – jedes Rendern verursacht echten Aufwand, also jeden Durchgang zählen lassen, anstatt nach jeder kleinen Änderung neu zu exportieren.
Den Export bei trivialen oder offensichtlichen Änderungen ganz überspringen.
Pre-Flight-Checkliste
Zusätzlich zur figma-use Pre-Flight-Checkliste Folgendes prüfen:
- Easing verwendet die öffentliche Form
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }– nicht interne Szenengraphen-Namen wieOUT_CUBIC. - Ease-in-out verwendet den exakten öffentlichen Enum
EASE_IN_AND_OUT(oderEASE_IN_AND_OUT_BACK); niemals den ungültigen AliasEASE_IN_OUTausgeben. - Der zu animierende Knoten ist kein oberster Frame (direktes Kind einer Seite). Stattdessen Nachkommen animieren.
- Zeitlinienwerte sind Sekunden in der öffentlichen Plugin-API. Über
setTimelineDurationverlängern; niemals verkürzen, es sei denn, der Benutzer hat darum gebeten. - Transform-Keyframe-Felder verwenden öffentliche Namen (
TRANSLATION_X,TRANSLATION_Y,ROTATION,SCALE_X,SCALE_Y,SCALE_XY), nicht interneMOTION_*Szenengraphen-Namen. - Manuelle Keyframe-Felder stammen aus der öffentlichen Whitelist in motion-patterns.md; generierte/interne Szenengraphen-Felder werfen absichtlich Fehler.
- Mutierte Knoten-IDs werden zurückgegeben (gemäß
figma-useRegel 15). - Wenn die Richtigkeit der Bewegung nicht offensichtlich ist und ein Frameextraktor (
ffmpeg) verfügbar ist, mittelsexport_video+ Framestichproben überprüfen – klein rendern, niedrigefps, iterieren, bis es stimmt (siehe Abschnitt „Überprüfen der Animation“ oben).get_screenshotzeigt nur den Ruhezustand.