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 Motion-Arbeiten aufgerufen wird. Nur Protokollierung.
Laufzeit-Sperre
Motion-APIs sind hinter dem User-Feature-Flag metronome_plugin_api gesperrt. Wenn der aufrufende Benutzer es nicht besitzt, wirft jede in diesem Skill referenzierte Motion-Eigenschaft und -Hilfsfunktion "<name>" is not a supported API.
Sofort bei diesem Fehler aussteigen. Nicht wiederholen; dem Benutzer mitteilen, dass Motion nicht für ihn aktiviert ist, und anhalten. Andernfalls werden Aufrufe verbraucht und der Benutzer durch ständig gleiche Fehlermeldungen verwirrt.
Wann dieser Skill zu verwenden ist
Diesen Skill laden, wann immer ein use_figma-Task 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 Zeitachsen-Dauer via
node.timelines/node.setTimelineDuration(id, seconds). - Auswahl von Easing für eine der obigen Aktionen.
Statische Designarbeit (Erstellen von Formen, Komponenten, Variablen, Layout) erfolgt ausschließlich über figma-use – dieser Skill ist nur für die Zeitdimension gedacht.
Verfügbare Motion-API-Oberfläche
node.manualKeyframeTracks– Lesen/Schreiben manueller Keyframes (inkl. Füll-, Strich- und Effekt-Spuren).node.applyManualKeyframeTrack(field, track)/node.removeManualKeyframeTrack(field)– Hinzufügen, Ersetzen oder Entfernen einer manuellen Keyframe-Spur, ohne das gesamte Objekt neu zu schreiben.node.animationStyles– Lesen/Schreiben von Animationsstil-Metadaten, die auf einen Knoten angewendet wurden.node.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)– Einen entdeckten Stil anwenden und eine angewandte Stilinstanz anhand ihrer zurückgegebenen/ausgelesenenidentfernen.node.timelines– Nur-Lesen-Liste der Zeitachsen für den enthaltenden Top-Level-Frame mit Dauern in Sekunden.node.setTimelineDuration(id, durationSeconds)– Schreiben der Zeitachsen-Dauer des enthaltenden Top-Level-Frames.node.animations– Nur-Lesen aufgelöste Keyframe-Daten (derzeit nur manuelle Spuren – siehe motion-patterns.md).figma.motion.figmaAnimationStyles()– Nur-Lesen-Liste der Erstanbieter-Animationsstile von Figma.
Das Erstellen von benutzerdefiniertem "figma:motion"-Preset-Modul-Quellcode ist nicht abgedeckt. Wenn der Benutzer einen brandneuen Animationsstil wünscht, dies mitteilen und anhalten; keinen erfinden.
Referenzdokumente
Diese nach Bedarf laden, basierend auf der Aufgabe:
| Dokument | Wann laden | Inhalt |
|---|---|---|
| motion-patterns.md | Hinzufügen/Bearbeiten von Bewegungsanimationen | Manuelle Keyframes, animierte Füllungen/Striche, Anwenden von Animationsstilen, Zeitachsen-Dauer |
| motion-easing.md | Einstellen von Animations-Easing | Keyframe-Easing-Objekte, benutzerdefinierte kubische/Feder, HOLD, Easing innerhalb eines Animationsstils anwenden |
Animation überprüfen
get_screenshot zeigt nur den Ruhezustand der Zeitachse, niemals Bewegung. Um Bewegung zu prüfen, export_video und Einzelbilder entnehmen – aber es rendert serverseitig und ist langsam und teuer (~10s bis Minuten), also jeden Render zählen lassen.
Vor dem Rendern planen – Die Kosten skalieren mit Pixel × Frames, also beides nicht größer halten als nötig:
- Zuerst die Momente auswählen. Pro Phase wird ein Frame benötigt (z. B. pro Staffelungsschritt oder Start / Mitte / Endposition), keine flüssige Wiedergabe – meist 4–6. Diese Anzahl bestimmt die fps.
- Größe auf das Nötigste beschränken. Klein anfangen –
constraint: { type: 'WIDTH', value: 320 },quality: "low"– aber Text und kleine Elemente werden dort unscharf, alsoWIDTHerhöhen (768+), wenn feine Details beurteilt werden müssen. Weglassen vonconstraint= volle Größe (1x; Server begrenzt auf 10x / 4096px). - fps gerade so hoch einstellen, dass diese Frames landen:
fps: 5reicht für einige wenige; 10 ist die Obergrenze. Höher bläht nur den Render auf.
Mechanik: export_video funktioniert nur auf einem Top-Level-Frame, dessen Kinder die Animation tragen (diesen Frame übergeben, nicht den Nachkommen, den man mit Keyframes versehen hat). Es gibt eine jobId mit status: "processing" zurück – erneut mit { fileKey, jobId } aufrufen, um abzufragen. Dann Frames lokal extrahieren mit ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png – Extraktion ist kostenlos, also sobald der Render bezahlt ist, jeden aussagekräftigen Frame daraus holen, statt neu zu exportieren. Ohne einen Frame-Extraktor wie ffmpeg den Export überspringen und über die Keyframes nachdenken.
Iterieren, bis es stimmt. Der Export ist eine Diagnose, keine Abnahme: Wenn die Frames falsch sind (falsche Reihenfolge, falsches Timing, fehlendes Element, Maske, die die Komposition ausblendet), die Keyframes/Styles korrigieren und neu exportieren. Alle Frames lesen und alle Korrekturen in einem Durchgang bündeln, bevor neu gerendert wird – jeder Render hat echten Overhead, also jeden zählen lassen, statt 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 prüfen:
- Easing verwendet die öffentliche Form
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }– keine internen Szenegraphen-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 Top-Level-Frame (direktes Kind einer Seite). Stattdessen Nachkommen animieren.
- Zeitachsen-Werte sind Sekunden in der öffentlichen Plugin-API. Verlängern via
setTimelineDuration; niemals verkürzen, es sei denn, der Benutzer hat es verlangt. - Transform-Keyframe-Felder verwenden öffentliche Namen (
TRANSLATION_X,TRANSLATION_Y,ROTATION,SCALE_X,SCALE_Y,SCALE_XY), keine internenMOTION_*-Szenegraphen-Namen. - Manuelle Keyframe-Felder stammen aus der öffentlichen Whitelist in motion-patterns.md; generierte/interne Szenegraphen-Felder werfen absichtlich Fehler.
- Mutierte Knoten-IDs werden zurückgegeben (gemäß
figma-useRegel 15). - Wenn Motion-Korrektheit nicht offensichtlich ist und ein Frame-Extraktor (
ffmpeg) verfügbar ist, viaexport_video+ Frame-Stichproben verifizieren – klein rendern, niedrigefps, iterieren, bis es stimmt (siehe Abschnitt „Animation überprüfen" oben).get_screenshotzeigt nur den Ruhezustand.