Que fait use_figma — Compétence d'animation pour l'API Figma ?
Contexte d'animation pour l'outil MCP use_figma. figma-use couvre les règles de base de l'API Plugin — chargez les deux ensemble.
Passez toujours skillNames: "figma-use-motion" (séparé par une virgule avec figma-use) lorsque vous appelez use_figma pour du travail d'animation. Uniquement pour la journalisation.
Barrière d'exécution
Les API d'animation sont protégées par le drapeau de fonctionnalité utilisateur metronome_plugin_api. Si l'utilisateur appelant ne le possède pas, chaque propriété et helper d'animation référencé dans cette compétence lève une erreur "<name>" n'est pas une API prise en charge.
Abandonnez rapidement sur cette erreur. Ne réessayez pas ; dites à l'utilisateur que l'animation n'est pas activée pour lui et arrêtez-vous. Sinon, vous gaspillez des appels et semez la confusion avec des échecs identiques répétés.
Quand utiliser cette compétence
Chargez cette compétence chaque fois qu'une tâche use_figma implique :
- L'ajout, la modification ou la suppression d'images clés sur un nœud (
manualKeyframeTracks,applyManualKeyframeTrack,removeManualKeyframeTrack). - L'animation des couleurs de remplissage ou de contour dans le temps.
- L'application, la modification ou la suppression de styles d'animation (
applyAnimationStyle,removeAnimationStyle,animationStyles). - La lecture ou l'écriture de la durée de la timeline via
node.timelines/node.setTimelineDuration(id, secondes). - Le choix d'un easing pour l'une des opérations ci-dessus.
Le travail de conception statique (création de formes, composants, variables, mise en page) passe uniquement par figma-use — cette compétence est réservée à la dimension temporelle.
Surface d'API d'animation exposée
node.manualKeyframeTracks— lecture/écriture des images clés manuelles (y compris les pistes de remplissage, de contour et d'effet).node.applyManualKeyframeTrack(champ, track)/node.removeManualKeyframeTrack(champ)— ajouter, remplacer ou supprimer une piste d'images clés manuelle sans réécrire tout l'objet.node.animationStyles— lecture/écriture des métadonnées de style d'animation appliquées à un nœud.node.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)— appliquer un style découvert et supprimer une instance de style appliquée via sonidretourné/lu en arrière.node.timelines— liste en lecture seule des timelines pour le cadre de premier niveau conteneur, avec des durées en secondes.node.setTimelineDuration(id, dureeSecondes)— écrire la durée de la timeline du cadre de premier niveau conteneur.node.animations— données d'images clés résolues en lecture seule (actuellement uniquement les pistes manuelles — voir motion-patterns.md).figma.motion.figmaAnimationStyles()— liste en lecture seule des styles d'animation propriétaires de Figma.
La création d'un code source de module prédéfini personnalisé "figma:motion" est hors de portée. Si l'utilisateur souhaite un tout nouveau style d'animation, dites-le et arrêtez-vous ; n'en inventez pas.
Documentation de référence
Chargez ces documents selon les besoins de la tâche :
| Doc | Quand charger | Ce qu'il couvre |
|---|---|---|
| motion-patterns.md | Ajout/modification d'animation de mouvement | Images clés manuelles, remplissages/contours animés, application de styles d'animation, durée de timeline |
| motion-easing.md | Réglage de l'easing d'animation | Objets d'easing pour images clés, courbe cubique/ressort personnalisée, HOLD, application de l'easing dans un style d'animation |
Vérification de l'animation
get_screenshot montre uniquement l'état de repos de la timeline, jamais le mouvement. Pour vérifier le mouvement, utilisez export_video et échantillonnez les images — mais le rendu est côté serveur, lent et coûteux (~10 s à minutes), alors faites en sorte que chaque rendu compte.
Planifiez avant de rendre — le coût évolue avec pixels × images, alors gardez les deux aussi petits que nécessaire :
- Choisissez d'abord les moments. Vous avez besoin d'une image par phase (par exemple, par étape de décalage, ou début / milieu / fin), pas d'une lecture fluide — généralement 4 à 6. Ce nombre détermine votre fps.
- Taillez à ce que vous devez lire. Commencez petit —
constraint: { type: 'WIDTH', value: 320 },quality: "low"— mais le texte et les petits éléments deviennent flous, donc augmentezWIDTH(768+) lorsque vous devez juger des détails fins. Omettreconstraint= pleine taille (1x ; le serveur limite à 10x / 4096 px). - Réglez fps juste assez haut pour capturer ces images :
fps: 5couvre quelques images ; 10 est une limite haute. Plus élevé ne fait que gonfler le rendu.
Mécanique : export_video fonctionne uniquement sur un cadre de premier niveau dont les enfants portent l'animation (passez ce cadre, pas le descendant que vous avez image clé). Il retourne un jobId avec status: "processing" — ré-invoquez avec { fileKey, jobId } pour interroger. Extrayez ensuite les images localement avec ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png — l'extraction est gratuite, donc une fois le rendu payé, exploitez-le pour chaque image qui vous renseigne plutôt que de ré-exporter. Sans extracteur d'images comme ffmpeg, sautez l'export et raisonnez sur les images clés à la place.
Itérez jusqu'à ce que ce soit juste. L'export est un diagnostic, pas une validation : si les images sont erronées (mauvais ordre, timing décalé, élément manquant, masque qui obscurcit le composite), corrigez les images clés/styles et ré-exportez. Lisez toutes les images et regroupez chaque correction en un seul passage avant de re-rendre — chaque rendu a un coût réel, donc faites en sorte que chacun compte plutôt que de ré-exporter après chaque petit changement.
Sautez complètement l'export pour les changements triviaux ou évidents.
Liste de vérification pré-vol
En plus de la liste de vérification pré-vol figma-use, vérifiez :
- L'easing utilise la forme publique
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }— pas les noms internes de graphe de scène commeOUT_CUBIC. - L'ease-in-out utilise l'énumération publique exacte
EASE_IN_AND_OUT(ouEASE_IN_AND_OUT_BACK) ; n'émettez jamais l'alias invalideEASE_IN_OUT. - Le nœud animé n'est pas un cadre de premier niveau (fils direct d'une page). Animez les descendants à la place.
- Les valeurs de timeline sont en secondes dans l'API Plugin publique. Prolongez via
setTimelineDuration; ne raccourcissez jamais sauf demande explicite de l'utilisateur. - Les champs d'images clés de transformation utilisent des noms publics (
TRANSLATION_X,TRANSLATION_Y,ROTATION,SCALE_X,SCALE_Y,SCALE_XY), pas les noms internesMOTION_*du graphe de scène. - Les champs d'images clés manuelles proviennent de la liste blanche publique dans motion-patterns.md ; les champs générés/internes du graphe de scène lèvent intentionnellement une erreur.
- Les ID des nœuds mutés sont retournés (conformément à la règle 15 de
figma-use). - Lorsque la correction du mouvement n'est pas évidente et qu'un extracteur d'images (
ffmpeg) est disponible, vérifiez viaexport_video+ échantillonnage d'images — rendez petit,fpsbas, itérez jusqu'à ce que ce soit juste (voir la section Vérification de l'animation ci-dessus).get_screenshotmontre uniquement l'état de repos.