Bewegung implementieren
Übersicht
Diese Fähigkeit führt die Übersetzung von Figma-Animationen und -Übergängen in ausführbaren Code (motion.dev, CSS-Keyframes oder frameworkspezifische Bibliotheken) durch.
Figma stellt Bewegung über zwei Tools bereit:
get_motion_context– das autoritative Bewegungstool. Gibt das vollständige Inventar der animierten Knoten, vorberechnete Code-Snippets (CSS@keyframes+ motion.dev), Fallback-Keyframe-Bindungen (falls keine Snippets verfügbar sind) und koordinierende Hinweise zur Timeline zurück. Die Quelle der Wahrheit für Animationsdaten und welche Knoten-IDs animieren.get_design_context– die Struktur des Designs: Layout, Größenangaben, Assets, Styling, Code Connect-Hinweise, Screenshot-Kontext und manchmal Bewegungsmarkierungen auf animierten Elementen (data-node-id, und bei geteilten Knotendata-motion-keys/data-motion-wrapper-for/data-motion-transform-template). Es kann einen animierten Knoten als einfaches Element (div,p,span, etc.) oder als Bewegungselement (motion.div) darstellen; es fügt die Animationswerte jedoch nicht inline ein.
Die beiden sind über die Knoten-ID verknüpft – das ist der gesamte Workflow. get_motion_context sagt dir, welche Knoten animieren und liefert die Keyframe-Werte, das Easing, das Timing und die Snippets. get_design_context sagt dir, wie diese Knoten aussehen und wo sie sich befinden. Für jeden Knoten in get_motion_context.nodes suche die passende data-node-id im Designkontext und füge die Bewegung in diese Struktur ein – ergänze oder umschließe ein motion.{tag}, wenn das Strukturelement einfach ist. Wenn der Designkontext eine Figma-Komponente wiederverwendet hat, kann der Bewegungsknoten auch fallbackNodeId enthalten; verwende diese nur als Fallback, nachdem die exakte nodeId versucht wurde.
Fähigkeitsgrenzen
- Verwende diese Fähigkeit, wenn das Ergebnis Bewegungscode im Repository des Benutzers ist.
- Wenn der Benutzer darum bittet, Animationen innerhalb von Figma selbst zu erstellen/bearbeiten, wechsle zu figma-use und folge stattdessen dieser Fähigkeit.
- Diese Fähigkeit deckt derzeit Animationen ab, wie sie von
get_motion_contextausgegeben werden (Snippets plus Fallback-Keyframe-Tracks, einschließlich vorgabengestützter Bewegung, die in diese Formen aufgelöst wurde). Breitere interaktive Variantenflüsse benötigen möglicherweise noch produktspezifische Zustandsbehandlungen im Code.
Voraussetzungen
- Figma MCP-Server verbunden und zugänglich.
- Knoten-ID aus der vom Benutzer bereitgestellten Figma-URL extrahiert. URL-Format:
https://figma.com/design/:fileKey/:fileName?node-id=1-2– extrahierefileKey(das Segment nach/design/) undnodeId(den Wert desnode-id-Query-Parameters, z.B.42-15). - Ziel-Codebasis. Das Bewegungsausgabeformat passt sich dem Stack an (siehe Framework-Empfehlungen).
Werkzeugauswahl
Verwende für die Bewegungsimplementierung beide Tools mit unterschiedlichen Rollen:
| Situation | Tool | Warum |
|---|---|---|
| Verstehen der statischen Struktur, Assets, Styles, Code Connect oder des visuellen Layouts | get_design_context | Liefert die Komponenten-/Seitencode-Referenz und die Asset-URLs, die du benötigst, um animierte Knoten korrekt zu platzieren. |
| Abrufen von Animationsdaten für jeden Knoten | get_motion_context | Speziell für Bewegung entwickelt und die Quelle der Wahrheit für Timing, Easing, Snippets und Keyframes. |
Ein Knoten hat Bewegungsmarkierungen (data-motion-keys, data-motion-wrapper-for) | Markierungen für die geteilte Platzierung, get_motion_context für die Werte | Geteilte Markierungen sagen dir, welche Tracks zu welchem Element gehören; die Keyframes/Easing/Timings und das Inventar der animierten Knoten kommen von get_motion_context. |
get_motion_context akzeptiert recursive: true (begrenzt auf 500 Knoten), wenn du die Bewegung der Nachkommen in einem Aufruf benötigst.
Erforderlicher Workflow
Schritt 1: Bestätige, dass der statische Designkontext verfügbar ist
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
Wenn get_design_context bereits für diesen Knoten aufgerufen wurde, verwende diese Ausgabe erneut. Wenn nicht, rufe es jetzt normal auf.
Verwende es als die maßgebliche Struktur – Hierarchie, Größen, Styling, Assets, Code Connect-Hinweise, Screenshot-Kontext und alle Bewegungsplatzierungsmarkierungen, die es zufällig enthält (Schritt 3). Das Inventar der animierten Knoten und die Animationswerte stammen von get_motion_context (Schritt 2).
Schritt 2: Rufe autoritative Bewegungsdaten ab
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
Antwortform (ein Eintrag pro animiertem Knoten):
codeSnippets– vorab generierte CSS@keyframesund motion.dev-Strings. Verwende diese direkt. Generiere sie nicht aus Fallback-Track-Daten neu.keyframeBindings– gebundene Keyframe-Tracks, einschließlich vorlagengestützter Bewegung, die in Track-Daten aufgelöst wurde, nur als Fallback-Daten enthalten, wenn beide Snippet-Formate fehlen.fallbackNodeId– optionale Fallback-ID für die Zuordnung zu komponentisiertem Designkontext. WennnodeIdeine instanzqualifizierte ID wieI4005:6111;30:8005ist, kann D2R den wiederverwendbaren Komponentenkörper mit der zugrunde liegenden Komponenten-ID rendern, z.B.4002:3957. In diesem Fall istfallbackNodeIddiedata-node-id, nach der gesucht werden soll, wenn die exaktenodeId-Suche fehlschlägt.
Rekursive Antworten können auch timelineCohorts enthalten: Gruppen von animierten Knoten-IDs, die eine gemeinsame Timeline-Wurzel, Dauer und Abspielmodus (once, loop oder boomerang) teilen. Verwende Kohorten, um gestaffelte oder Multi-Knoten-Animationen synchron zu halten, anstatt das gemeinsame Timing aus der Geschwisterreihenfolge abzuleiten.
Implementierungsdetails, die für LLMs wichtig sind:
- Wenn Snippets existieren, können rohe
keyframeBindings,timelineDurationMs,motionSummaryund standardmäßigestransformOriginentfernt werden, um die Nutzlast klein zu halten. FehlendekeyframeBindingssind kein Zeichen dafür, dass es keine Animation gibt. - Rekursive Antworten deduplizieren exakt doppelte Snippets. Ein Snippet kann durch einen Kommentar ersetzt werden, der auf den ersten Knoten mit identischer Bewegung verweist; verwende dieselbe Komponente, Variante, Klasse oder Konstanten erneut, anstatt eine zweite Animation zu schreiben.
- Der MCP-Server leitet CSS- vs. motion.dev-Snippets aus
clientFrameworksab; wenn die Antwort nur ein Snippet-Format enthält, passe dieses Format an den Stack des Benutzers an, anstatt anzunehmen, dass das andere Format fehlgeschlagen ist.
Schritt 3: Führe statischen und Bewegungskontext zusammen
- Beginne mit
get_motion_context.nodes, nicht mit sichtbarenmotion.*-Tags im statischen JSX. Jeder zurückgegebene Knoten ist animiert. Ordne jeden Bewegungsknoten zuerst der exaktennodeId/data-node-idimget_design_contextzu. Wenn und nur wenn es keine exakte Übereinstimmung gibt, versuche es mitfallbackNodeId/data-node-id. Verwende Knotennamen/-typ und Screenshot-Position nur als letzten Ausweg, wenn beide IDs fehlschlagen. - Exakte ID-Übereinstimmung gewinnt vor
fallbackNodeId.fallbackNodeIdzeigt auf die zugrunde liegende Komponenten-ID, die D2R innerhalb einer wiederverwendbaren Komponente ausgeben kann. Sie wird von jeder Instanz dieser Komponente geteilt. Wenn die exaktenodeIdim Designkontext existiert, wende die Bewegung dort an und ignoriere den Fallback. Dies ist entscheidend für die Animation der Stamm-Instanz: Eine Instanz kann sich anders drehen oder bewegen als eine andere Instanz derselben Komponente, und das Anwenden dieser Bewegung auf den gemeinsamen Komponentenkörper würde alle Instanzen falsch animieren. - Wende jeden Bewegungsknoten auf die passende Designkontext-Struktur an, verknüpft mit
data-node-id. Die passendedata-node-idist der strukturelle Anker, nicht immer das endgültige DOM-Element, das die Bewegung erhält. Verwende die Snippet-Form und Platzierungsmarkierungen, um zu entscheiden, ob die Bewegung auf diesem exakten Element, einem Wrapper, einem inneren Element oder einem inline-SVG-Pfad landen soll.get_design_contextkann bereitsmotion.{tag}mit entfernten Werten ausgeben, oder es kann ein einfaches Strukturelement (div,p,span, Komponentenwurzel, etc.) ausgeben. Wenn es einfach ist und das Snippet auf das Element selbst abzielt, wandle es in das entsprechendemotion.{tag}um oder füge einen Bewegungswrapper hinzu, während der Text, die Kinder, die Klassen/Styles, die Attribute und diedata-node-iddes Knotens erhalten bleiben. Lade references/examples-and-anti-examples.md, um Beispiele für diesen Zusammenführungsschritt zu sehen. - Komponentisierte Kind-Bewegung wird normalerweise über den Fallback zugeordnet. Wenn der Designkontext eine Figma-Instanz in eine wiederverwendbare React-Komponente extrahiert, haben Kinder innerhalb des Komponentenkörpers oft zugrunde liegende Komponenten-IDs (
4002:3957), während der Bewegungskontext Live-Instanz-IDs (I4005:6111;30:8005) meldet. Verwende in diesem FallfallbackNodeId, um diedata-node-iddes Komponentenkörpers zu finden, aber behalte die Bewegung auf die gerenderte Instanz beschränkt, die du implementierst. Wenn es mehrere Instanzen gibt und nur eine eine andere Stamm-Bewegung hat, hält die exakte ID-Zuordnung diese instanzspezifische Bewegung getrennt. - Geteilte Knoten tragen eine
data-motion-keys/data-motion-wrapper-for-Markierung – siehe Umgang mit verschachtelten Transformationen unten. - Behalte
display: contents-Wrapper bei – es sei denn, die Gruppe selbst animiert. Layout-transparente Gruppen-Wrapper kommen alscontents(Tailwindcontents) durch, normalerweise zusammen mit einem totenabsolute/inset-[…](das bewirkt nichts bei einercontents-Box). Belasse bei einer statischen Gruppedisplay: contentsund lasse die Kinder sich gegen den nächsten echten Vorfahren positionieren – das Umwandeln desinsetdes Wrappers in eine positionierte Box führt dazu, dass die Kinder an eine kleinere Box gebunden werden und daher zu klein / nach innen verschoben rendern. Bei einer animierten Gruppe (der Gruppenknoten selbst hat Bewegung) kanndisplay: contentskeine Transformation tragen – ersetze es durch einen echten positionierten Wrapper und wende die Gruppenbewegung dort an. Lade references/gotchas.md vor der Implementierung dieses Falls. get_motion_contextist das vollständige Inventar der animierten Knoten. Einige animierte Knoten werden als einfache (nicht-motion) Elemente gerendert – Komponenteninstanz-Wurzeln (einfach positionierendes<div>), Text (<p>), Masken – die dennoch einedata-node-idtragen. Gehe jeden Knoten in der Bewegung zugrunde liegenden Antwort durch und wende seine Bewegung auf das Element mit der passendendata-node-idan, wobei du es nach Bedarf umschließt oder konvertierst. Wenn ein animierter Knoten überhaupt kein Element in der Ausgabe hat (z. B. eine animierte Maske, die in ein statischesmask-imageintegriert wurde), lasse es nicht stillschweigend weg – hinterlasse einen// TODO: <nodeId> motion unsupported-Kommentar und weise in deiner Zusammenfassung darauf hin.- Wenn ein Knoten im Bewegungskontext, aber nicht im statischen JSX erscheint, füge das benötigte Element hinzu, um ihn darzustellen – der Code des Designkontexts ist eine Referenz, kein vollständiges Animationsinventar.
- Bei Konflikten zwischen Design- und Bewegungskontext (Timing/Easing/animierte Werte) bevorzuge
get_motion_context. - SVG-Bewegung auf Pfadebene: Binde das SVG inline ein und animiere den echten
<path>. Wennget_motion_contextauf den Pfad eines Vektors abzielt (PATH_TRIM,motion.path,stroke-dasharray), der Designkontext es aber als<img>rendert, binde das SVG inline ein und wende das Snippet auf den<path>an, wobei der Layout-Wrapper erhalten bleibt. Lade references/svg-and-path-motion.md für die vollständige Anleitung zu diesem Fall (motion.path,pathLength="1", Wrapper+Pfad-Schichtung, CSS-Pfad-Trim).
Umgang mit verschachtelten Transformationen
Ein Knoten mit sowohl einer statischen Basistransformation als auch animierten Transformationen wird über verschachtelte Elemente aufgeteilt, sodass die beiden korrekt zusammenspielen, anstatt sich zu bekämpfen: ein id-loses motion.div, das data-motion-wrapper-for="<nodeId>" trägt (der ÄUSSERE Wrapper), umschließt ein statisches Transformations-div (z. B. rotate-45 + hypot()-Größenanpassung – oder der Wrapper selbst trägt data-motion-transform-template="<css>"), das den INNEREN Knoten (data-node-id) umschließt. Behalte die Wrapper > statisches-Transformations-div > Inneres-Verschachtelung bei – das Zusammenführen zerstört die Größenanpassung und die Basistransformation.
- Platziere Tracks über
data-motion-keys. Diedata-motion-keysdes Wrappers (Transformations-Tracks –x/y/rotate/scaleX/scaleY/skewX) gehen auf den ÄUSSEREN Wrapper; diedata-motion-keysdes inneren Elements gehen auf das INNERE Element. - Wende eine
data-motion-transform-templateerneut an. Wenn der Wrapper eine trägt, setzetransformTemplate={(_, generated) => "<css> " + generated}, sodass die animierte Transformation auf dieser statischen Layout-Transformation aufbaut. - Verschiebe die animierte Transformation um die statische Basis (vermeide doppelte Drehung).
get_motion_contextliefert die absolute Transformation des Knotens, die bereits die statische Basis dieser divs enthält. Einrotate-Snippet von[45, 125, 125]über einerrotate-45-Basis bedeutet, dass der Wrapper den Offset[0, 80, 80](= absolut − 45) animiert, nicht den absoluten – sonst wird die 45° doppelt angewendet und das Element liegt im Ruhezustand bei 90°. Tracks ohne statische Basis (z. B.x/ybeginnend bei 0) werden unverändert durchgereicht. Siehe das Beispiel für verschachtelte Transformationen. - Halte Layout-Transformationen getrennt von Motion-Transformationen. Überprüfe für jedes
motion.*-Element, dasrotate,scaleoderskewanimiert, dass es nicht auch auf Tailwind-Layout-Transformationen wie-translate-x-1/2oder-translate-y-1/2zur Zentrierung/Positionierung angewiesen ist. Diese Hilfsprogramme teilen sich die CSS-transform-Eigenschaft, die Motion.dev inline schreibt, sodass die Motion-Transformation die Layout-Übersetzung löschen kann. Wenn beide benötigt werden, teile das Element auf in einen statischen Layout-Wrapper, der die Zentrierungs-/Positionierungstransformation trägt, und ein inneresmotion.*-Element, das die animierte Drehung/Skalierung/Opazität trägt, oder kodiere den Layout-Offset in Motion selbst (x: "-50%") und halte ihn für jeden Keyframe präsent.
Schritt 4: Wende die Bewegung im Code an
- motion.dev in den Snippets vorhanden? Verwende den motion.dev-Code wörtlich für React-Ziele. Importiere aus
motion/react– es sei denn, die Codebasis verwendet bereits eine andere Bewegungsbibliothek (Framer Motion, React Spring, GSAP); in diesem Fall passe das Snippet daran an. Lade references/framework-recommendations.md, wenn du an einen anderen Stack anpasst oder eine Bibliothek auswählst. - CSS-Keyframes vorhanden? Verwende sie für Vanilla-/Nicht-React-Ziele oder wenn die Codebasis keine React-Bewegungsbibliothek hat.
- Keine Snippets? Verwende
keyframeBindingsodermotionSummaryals Fallback-Daten, um entsprechende motion.dev-Aufrufe oder CSS-Keyframes zu konstruieren. Normalerweise sind Snippets vorhanden; tue dies nur, wenn beide Snippet-Formate tatsächlich fehlen.
Schritt 5: Validieren
- Lies die vorhandenen Bewegungs-Importe/Konventionen der Komponente, bevor du neue hinzufügst. Wenn der Benutzer bereits Framer Motion / React Spring / anime.js verwendet, passe dich an, anstatt motion.dev zu erzwingen.
- Überprüfe eine Animation stichprobenartig Ende-zu-Ende (lade neu, beobachte, iteriere), bevor du Änderungen über viele Knoten hinweg bündelst.
- Lade references/gotchas.md und überprüfe die Liste der bekannten Fallstricke, nachdem die Implementierung für einen Satz von Knoten abgeschlossen ist, um sicherzustellen, dass keine häufigen Fehler übersehen wurden.
- Lade references/edge-cases-and-known-issues.md und überprüfe, ob einer der dokumentierten Randfälle auf deine aktuelle Implementierung zutrifft.
Framework-Empfehlungen
| Framework | Vorgeschlagene Bibliothek | Snippet-Ausgabe von get_motion_context |
|---|---|---|
| React & JSX-Bibliotheken | motion/react | Beide Formate (motion.dev + CSS) vorhanden. Verwende motion.dev, da es am flexibelsten ist. |
| Vue 3 | motion/vue | Beide Formate vorhanden. motion/vue mit <Motion>-Tag ist idiomatisch. |
| Svelte | motion/svelte | Beide Formate vorhanden. motion/svelte mit Svelte-Bewegungs-Direktiven ist idiomatisch. |
| Vanilla JS (kein Framework) | N/A (CSS) | Verwende die CSS-Keyframes direkt. |
| React mit vorhandener Bibliothek | Erhalte vorhandene Bibliothek | Passe die motion.dev-Snippets an die API der vorhandenen Bibliothek an. |
Wähle immer motion/react, es sei denn, der Benutzer hat eine andere Bibliothek ausdrücklich festgelegt oder die Codebasis hat eine erkennbare vorhandene Bewegungsabhängigkeit.
Wenn das Projekt eine eigenständige Seite ist (Next.js / Vite / CRA), installiere motion als Abhängigkeit, falls nicht vorhanden.
Motion dev vs. CSS
- motion.dev-Code ist der empfohlene Standard für React/JSX-Elemente. Er ermöglicht natürliche Deklaration von Wiedergabesteuerungen, Varianten, Layout-Animationen, unscharfen Animationen und Übergängen, die sich mit CSS-Keyframes nicht gut oder gar nicht ausdrücken lassen. Vom MCP-Server generierte motion.dev-Code-Snippets sind gebrauchsfertig.
- CSS
@keyframessind ausreichend für einfache, sich wiederholende Animationen, bei denen keine Laufzeitlogik erforderlich ist. Wenn das Ziel (z. B. statischer HTML-Export) keine Laufzeit für motion.dev zulässt, sind CSS-Keyframes die einzig sinnvolle Option.
Keine Ausgabe ignorieren. Liefert der Server sowohl motion.dev- als auch CSS-Keyframe-Snippets, verwende motion.dev für die Code-Implementierung und CSS nur, wenn motion.dev nicht verfügbar ist.
Code-Konventionen
- Code Connect Annotationen respektieren. Der Designkontext kann Code Connect-Hinweise enthalten. Wenn
get_design_contextangibt, dass bestimmte Klassen, Stützeigenschaften oder Konfigurationen verwendet werden sollen, priorisiere diese gegenüber den generischen Vorgaben. - CSS-Variablen für Farben/Abstände beibehalten. Wenn das Design CSS-Variablen (
--color-primary,--spacing-md) verwendet, verwende sie im Code. - Bewegungs-Code auf Komponentenebene konsistent halten. Wenn eine Komponente eine Instanz mit einer Bewegung erstellt, verwende für die umgebende Komponente nach Möglichkeit dieselbe Bibliothek, denselben Importpfad und dieselbe Syntax.
Fähigkeiten-Bereitstellung und Problembehandlung
- Screenshots zuerst: Wenn der Screenshot nicht geladen werden kann, verwende eine Kombination aus Knoten- und Komponente zugrunde liegenden Beschreibungen als Ausweichlösung.
- Fehlerbehandlung: Der MCP-Server kann Tools mit Fehlermeldungen ablehnen. Wenn ein Tool fehlschlägt, lies die Fehlermeldung, behebe das Problem (z. B. fehlerhafte Knoten-ID) und versuche es erneut.
- Miniaturansichten nicht ignorieren: Verwende Screenshot-Miniaturansichten, um die visuelle Position jedes Knotens innerhalb der verbleibenden Layout-Hierarchie zu validieren.