Implémenter le Mouvement
Aperçu
Cette compétence guide la traduction des animations et transitions Figma en code exécutable (motion.dev, keyframes CSS ou bibliothèques spécifiques au framework).
Figma expose le mouvement via deux outils :
get_motion_context— outil de mouvement faisant autorité. Renvoie l'inventaire complet des nœuds animés, des extraits de code précalculés (CSS@keyframes+ motion.dev), des liaisons de keyframes de secours lorsque les extraits ne sont pas disponibles, et des indices de coordination de timeline récursive. Source de vérité pour les données d'animation et les ID de nœuds animés.get_design_context— la structure de la conception : disposition, dimensions, assets, style, indices Code Connect, contexte de capture d'écran et parfois des marqueurs de placement de mouvement sur les éléments animés (data-node-id, et sur les nœuds divisésdata-motion-keys/data-motion-wrapper-for/data-motion-transform-template). Il peut afficher un nœud animé comme un élément simple (div,p,span, etc.) ou un élément motion (motion.div) ; il n'intègre pas les valeurs d'animation.
Les deux sont liés par l'ID de nœud, et c'est tout le flux de travail. get_motion_context vous indique quels nœuds sont animés et donne les valeurs de keyframes, l'easing, le timing et les extraits. get_design_context vous indique à quoi ressemblent ces nœuds et où ils se situent. Pour chaque nœud dans get_motion_context.nodes, trouvez le data-node-id correspondant dans le contexte de conception et fusionnez le mouvement dans cette structure — en ajoutant ou en enveloppant un motion.{tag} lorsque l'élément structurel est simple. Lorsque le contexte de conception a réutilisé un composant Figma, le nœud de mouvement peut également inclure fallbackNodeId ; utilisez-le uniquement comme solution de secours après avoir essayé le nodeId exact.
Limites de la Compétence
- Utilisez cette compétence lorsque le livrable est un code de mouvement dans le dépôt de l'utilisateur.
- Si l'utilisateur demande de créer/modifier des animations directement dans Figma, passez à figma-use et suivez cette compétence à la place.
- Cette compétence couvre actuellement les animations telles qu'émises par
get_motion_context(extraits plus pistes de keyframes de secours, y compris le mouvement créé par préréglage résolu dans ces formes). Les flux de variantes interactives plus larges peuvent encore nécessiter une gestion d'état spécifique au produit dans le code.
Prérequis
- Serveur MCP Figma connecté et accessible.
- ID de nœud extrait de l'URL Figma fournie par l'utilisateur. Format de l'URL :
https://figma.com/design/:fileKey/:fileName?node-id=1-2— extrayezfileKey(le segment après/design/) etnodeId(la valeur du paramètre de requêtenode-id, par exemple42-15). - Codebase cible. Le format de sortie du mouvement s'adapte à la pile (voir Recommandations pour le Framework).
Choix de l'Outillage
Pour l'implémentation du mouvement, utilisez les deux outils avec des rôles distincts :
| Situation | Outil | Pourquoi |
|---|---|---|
| Comprendre la structure statique, les assets, les styles, Code Connect ou la disposition visuelle | get_design_context | Donne la référence du code du composant/page et les URL des assets nécessaires pour placer correctement les nœuds animés. |
| Récupérer les données d'animation pour n'importe quel nœud | get_motion_context | Conçu spécifiquement pour le mouvement et source de vérité pour le timing, l'easing, les extraits et les keyframes. |
Un nœud a des marqueurs de mouvement (data-motion-keys, data-motion-wrapper-for) | Marqueurs pour le placement divisé, get_motion_context pour les valeurs | Les marqueurs de division vous indiquent quelles pistes vont sur quel élément ; les keyframes/easing/timing et l'inventaire des nœuds animés proviennent de get_motion_context. |
get_motion_context accepte recursive: true (limité à 500 nœuds) lorsque vous avez besoin du mouvement des descendants en un seul appel.
Flux de Travail Requis
Étape 1 : Confirmer que le contexte de conception statique est disponible
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
Si get_design_context a déjà été appelé pour ce nœud, réutilisez cette sortie. Sinon, appelez-le normalement maintenant.
Utilisez-le comme structure de référence — hiérarchie, dimensions, style, assets, indices Code Connect, contexte de capture d'écran et tous les marqueurs de placement de mouvement qu'il contient éventuellement (Étape 3). L'inventaire des nœuds animés et les valeurs d'animation proviennent de get_motion_context (Étape 2).
Étape 2 : Récupérer les données de mouvement faisant autorité
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
Forme de la réponse (une entrée par nœud animé) :
codeSnippets— chaînes CSS@keyframeset motion.dev pré-générées. Utilisez-les directement. Ne les régénérez pas à partir des données de piste de secours.keyframeBindings— pistes de keyframes liées, y compris le mouvement dérivé de préréglage résolu en données de piste, incluses uniquement comme données de secours lorsque les deux formats d'extrait sont manquants.fallbackNodeId— ID de secours facultatif pour faire correspondre le contexte de conception componentisé. SinodeIdest un ID qualifié d'instance tel queI4005:6111;30:8005, D2R peut afficher le corps du composant réutilisable avec l'ID du composant de base à la place, par exemple4002:3957. Dans ce cas,fallbackNodeIdest ledata-node-idà rechercher si la recherche exacte denodeIdéchoue.
Les réponses récursives peuvent également inclure timelineCohorts : des groupes d'ID de nœuds animés qui partagent une racine de timeline, une durée et un mode de lecture (once, loop ou boomerang). Utilisez les cohortes pour maintenir la synchronisation des animations décalées ou multi-nœuds au lieu de déduire un timing partagé de l'ordre des frères.
Détails d'implémentation importants pour les LLM :
- Lorsque des extraits existent, les
keyframeBindings,timelineDurationMs,motionSummarybruts et letransformOriginpar défaut peuvent être supprimés pour garder la charge utile petite. L'absence dekeyframeBindingsn'est pas un signal qu'il n'y a pas d'animation. - Les réponses récursives dédoublonnent les extraits en double exact. Un extrait peut être remplacé par un commentaire pointant vers le premier nœud avec un mouvement identique ; réutilisez le même composant, la même variante, la même classe ou les mêmes constantes au lieu d'écrire une deuxième animation.
- Le serveur MCP déduit les extraits CSS vs motion.dev à partir de
clientFrameworks; si la réponse ne contient qu'un format d'extrait, adaptez ce format à la pile de l'utilisateur plutôt que de supposer que l'autre format a échoué.
Étape 3 : Fusionner les contextes statique et de mouvement
- Commencez par
get_motion_context.nodes, pas par les balisesmotion.*visibles dans le JSX statique. Chaque nœud renvoyé est animé. Faites correspondre chaque nœud de mouvement auget_design_contextparnodeId/data-node-idexact d'abord. Si et seulement s'il n'y a pas de correspondance exacte, essayezfallbackNodeId/data-node-id. Revenez au nom/type de nœud et à la position de la capture d'écran uniquement après l'échec des deux ID. - La correspondance d'ID exacte l'emporte sur
fallbackNodeId.fallbackNodeIdpointe vers l'ID du composant de base que D2R peut émettre à l'intérieur d'un composant réutilisable. Il est partagé par chaque instance de ce composant. Si lenodeIdexact existe dans le contexte de conception, appliquez le mouvement là et ignorez le fallback. Ceci est crucial pour l'animation racine d'instance : une instance peut tourner ou se déplacer différemment d'une autre instance du même composant, et appliquer ce mouvement au corps du composant partagé animerait toutes les instances de manière incorrecte. - Appliquez chaque nœud de mouvement à la structure du contexte de conception correspondante, indexée par
data-node-id. Ledata-node-idcorrespondant est le point d'ancrage structurel, pas toujours l'élément DOM final qui reçoit le mouvement. Utilisez la forme de l'extrait et les marqueurs de placement pour décider si le mouvement va sur cet élément exact, un wrapper, un élément interne ou un chemin SVG en ligne.get_design_contextpeut déjà émettremotion.{tag}avec des valeurs supprimées, ou il peut émettre un élément structurel simple (div,p,span, racine de composant, etc.). S'il est simple et que l'extrait cible l'élément lui-même, convertissez-le enmotion.{tag}approprié ou ajoutez un wrapper de mouvement tout en préservant le texte, les enfants, les classes/styles, les attributs etdata-node-iddu nœud. Chargez references/examples-and-anti-examples.md pour voir des exemples de cette étape de fusion. - Le mouvement enfant componentisé correspond généralement par fallback. Lorsque le contexte de conception extrait une instance Figma dans un composant React réutilisable, les enfants à l'intérieur du corps de ce composant ont souvent des ID de composant de base (
4002:3957) tandis que le contexte de mouvement rapporte des ID d'instance en direct (I4005:6111;30:8005). Dans ce cas, utilisezfallbackNodeIdpour trouver ledata-node-iddu corps du composant, mais gardez le mouvement limité à l'instance rendue que vous implémentez. S'il y a plusieurs instances et qu'une seule a un mouvement racine différent, la correspondance d'ID exacte maintient ce mouvement par instance séparé. - Les nœuds divisés portent un marqueur
data-motion-keys/data-motion-wrapper-for— voir Gestion des transformations entrelacées ci-dessous. - Conservez les wrappers
display: contents— sauf si le groupe lui-même est animé. Les wrappers de groupe transparents pour la disposition arrivent en tant quecontents(Tailwindcontents), généralement accompagnés d'unabsolute/inset-[...]mort (ceux-ci ne font rien sur une boîtecontents). Pour un groupe statique, conservezdisplay: contentset laissez les enfants se positionner par rapport à l'ancêtre réel le plus proche — la conversion de l'insetdu wrapper en une boîte positionnée re-parente les enfants vers une boîte plus petite, donc ils s'affichent trop petits / décalés vers l'intérieur. Pour un groupe animé (le nœud du groupe lui-même a un mouvement),display: contentsne peut pas porter de transformation — remplacez-le par un wrapper positionné réel et appliquez le mouvement du groupe là. Chargez references/gotchas.md avant d'implémenter ce cas. get_motion_contextest l'inventaire complet des nœuds animés. Certains nœuds animés s'affichent comme des éléments simples (nonmotion) — racines d'instance de composant (<div>de positionnement simple), texte (<p>), masques — qui portent toujours undata-node-id. Parcourez chaque nœud dans la réponse de mouvement et appliquez son mouvement à l'élément avec ledata-node-idcorrespondant, en enveloppant ou convertissant si nécessaire. Si un nœud animé n'a aucun élément du tout dans la sortie (par exemple, un masque animé aplati en unmask-imagestatique), ne le supprimez pas silencieusement — laissez un commentaire// TODO: <nodeId> mouvement non pris en chargeet signalez-le dans votre résumé.- Si un nœud apparaît dans le contexte de mouvement mais pas dans le JSX statique, ajoutez l'élément nécessaire pour le représenter — le code du contexte de conception est une référence, pas un inventaire d'animation complet.
- En cas de conflit entre le contexte de conception et celui de mouvement (timing/easing/valeurs animées), privilégiez
get_motion_context. - Mouvement SVG au niveau du chemin : inlinez le SVG et animez le vrai
<path>. Lorsqueget_motion_contextcible le chemin d'un vecteur (PATH_TRIM,motion.path,stroke-dasharray) mais que le contexte de conception le rend en tant que<img>, inlinez le SVG et appliquez l'extrait au<path>, en conservant le wrapper de disposition. Chargez references/svg-and-path-motion.md pour le guide complet pour ce cas (motion.path,pathLength="1", wrapper+path layering, CSS path-trim).
Gestion des transformations entrelacées
Un nœud avec à la fois une transformation de base statique et des transformations animées est divisé en éléments imbriqués afin que les deux se composent correctement au lieu de se battre : un motion.div sans ID portant data-motion-wrapper-for="<nodeId>" (le wrapper EXTERNE) enveloppe un div de transformation statique (par exemple rotate-45 + dimensionnement hypot() — ou le wrapper lui-même porte data-motion-transform-template="<css>") qui enveloppe le nœud INTERNE (data-node-id). Conservez l'imbrication wrapper > div de transformation statique > interne — son effondrement casse le dimensionnement et la transformation de base.
- Placez les pistes par
data-motion-keys. Lesdata-motion-keysdu wrapper (pistes de transformation —x/y/rotate/scaleX/scaleY/skewX) vont sur le wrapper EXTERNE ; lesdata-motion-keysde l'élément interne vont sur l'élément INTERNE. - Réappliquez un
data-motion-transform-template. Si le wrapper en porte un, définisseztransformTemplate={(_, generated) => "<css> " + generated}afin que la transformation animée se compose au-dessus de cette transformation de disposition statique. - Décalez la transformation animée par la base statique (éviter la double rotation).
get_motion_contextdonne la transformation absolue du nœud, qui inclut déjà la base statique que ces divs appliquent. Un extraitrotatede[45, 125, 125]sur une baserotate-45signifie que le wrapper anime le décalage[0, 80, 80](= absolu − 45), pas l'absolu — sinon le 45° s'applique deux fois et l'élément se trouve à 90° au repos. Les pistes sans base statique (par exemplex/ycommençant à 0) passent inchangées. Voir l'exemple de transformation entrelacée. - Gardez les transformations de disposition séparées des transformations Motion. Pour chaque élément
motion.*qui animerotate,scaleouskew, vérifiez qu'il ne repose pas également sur des transformations de disposition Tailwind telles que-translate-x-1/2ou-translate-y-1/2pour le centrage/positionnement. Ces utilitaires partagent la propriété CSStransformque Motion.dev écrit en ligne, donc la transformation de Motion peut effacer la translation de disposition. Si les deux sont nécessaires, divisez l'élément en un wrapper de disposition statique portant la transformation de centrage/positionnement et un élémentmotion.*interne portant rotate/scale/opacity animé, ou encodez le décalage de disposition dans Motion lui-même (x: "-50%") et maintenez-le présent pour chaque keyframe.
Étape 4 : Appliquer le mouvement dans le code
- motion.dev présent dans les extraits ? Utilisez le code motion.dev textuellement pour les cibles React. Importez depuis
motion/react— sauf si la base de code utilise déjà une autre bibliothèque de mouvement (Framer Motion, React Spring, GSAP), auquel cas adaptez l'extrait à celle-ci. Chargez references/framework-recommendations.md lors de l'adaptation à une autre pile ou du choix d'une bibliothèque. - Keyframes CSS présents ? Utilisez pour les cibles vanilla/non-React, ou lorsque la base de code n'a pas de bibliothèque de mouvement React.
- Pas d'extraits ? Utilisez
keyframeBindingsoumotionSummarycomme données de secours pour construire des appels motion.dev ou des keyframes CSS équivalents. Normalement, les extraits sont présents ; ne faites cela que lorsque les deux formats d'extrait sont vraiment manquants.
Étape 5 : Valider
- Lisez les importations/conventions de mouvement existantes du composant avant d'en ajouter de nouvelles. Si l'utilisateur utilise déjà Framer Motion / React Spring / anime.js, adaptez plutôt que de forcer motion.dev.
- Vérifiez ponctuellement qu'une animation s'exécute de bout en bout (rechargez, observez, itérez) avant de traiter les modifications sur plusieurs nœuds.
- Chargez references/gotchas.md avant d'implémenter l'un de ces cas délicats.
Recommandations pour le Framework
(Le fichier references/framework-recommendations.md contient des directives spécifiques ; chargez-le lorsque vous devez choisir une approche pour une pile donnée.)
Exemples et Anti-exemples
(Le fichier references/examples-and-anti-examples.md contient des exemples détaillés de l'étape de fusion de l'Étape 3.)
Mouvement SVG et de Chemin
(Le fichier references/svg-and-path-motion.md contient le guide complet pour les animations SVG.)
Pièges
(Le fichier references/gotchas.md documente les cas délicats : le dimensionnement des wrappers de transformation entrelacée, les animations de groupe avec display: contents, les conflits de transformation de disposition, etc.)
Résumé du Flux de Travail
URL Figma → get_design_context (structure statique)
→ get_motion_context (données d'animation)
→ Fusion par ID de nœud (get_motion_context.nodes → correspondance data-node-id)
→ Appliquer les extraits de mouvement ou les keyframes de secours
→ Valider dans le navigateur