use_figma — モーションのためのFigmaプラグインAPIスキル
use_figma MCPツールのモーションコンテキスト。figma-use が基本的なプラグインAPIルールをカバーしています。両方を一緒にロードしてください。
モーションワークのために use_figma を呼び出すときは、常に skillNames: "figma-use-motion" (figma-use とカンマ区切りで)を渡してください。 ログのみの目的です。
ランタイムゲーティング
モーションAPIは、metronome ユーザー機能フラグの背後にゲートされています。呼び出し元のユーザーがこのフラグを持っていない場合、このスキルで参照されるすべてのモーションプロパティとヘルパーは、"<name>" is not a supported API をスローします。
そのエラーが発生したらすぐに処理を中止してください。 リトライせず、ユーザーにモーションが有効になっていないことを伝えて停止してください。そうしないと、呼び出しを浪費し、同じ失敗を繰り返してユーザーを混乱させることになります。
このスキルを使用するタイミング
use_figma タスクに以下が含まれる場合は常に、このスキルをロードしてください。
- ノードへのキーフレームの追加、編集、削除(
manualKeyframeTracks、applyManualKeyframeTrack、removeManualKeyframeTrack) - 塗りつぶしまたはストロークの色の経時的なアニメーション化
- アニメーションスタイルの適用、編集、削除(
applyAnimationStyle、removeAnimationStyle、animationStyles) node.timelines/node.setTimelineDuration(id, seconds)によるタイムライン期間の読み取りまたは書き込み- 上記のいずれかのイージングの選択
静的なデザインワーク(シェイプ、コンポーネント、変数、レイアウトの作成)は、figma-use のみを通過します。このスキルは時間軸専用です。
公開モーションAPIサーフェス
node.manualKeyframeTracks— 手動キーフレームの読み取り/書き込み(塗りつぶし、ストローク、エフェクトトラックを含む)node.applyManualKeyframeTrack(field, track)/node.removeManualKeyframeTrack(field)— オブジェクト全体を書き換えずに、1つの手動キーフレームトラックを追加、置換、または削除しますnode.animationStyles— ノードに適用されたアニメーションスタイルメタデータの読み取り/書き込みnode.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)— 発見したスタイルを適用し、返された/読み戻されたidによって適用済みスタイルインスタンスを削除しますnode.timelines— 包含する最上位フレームの読み取り専用タイムラインリスト。期間は秒単位node.setTimelineDuration(id, durationSeconds)— 包含する最上位フレームのタイムライン期間を書き込みますnode.animations— 読み取り専用の解決済みキーフレームデータ(現在は手動トラックのみ — motion-patterns.md を参照)figma.motion.figmaAnimationStyles()— Figmaのファーストパーティアニメーションスタイルの読み取り専用リスト
カスタム "figma:motion" プリセットモジュールのソースコードを作成することは範囲外です。ユーザーが新しいアニメーションスタイルを希望する場合は、その旨を伝えて停止してください。でっち上げないでください。
リファレンスドキュメント
タスクに応じて、必要に応じてこれらをロードしてください。
| ドキュメント | ロードするタイミング | カバー内容 |
|---|---|---|
| motion-patterns.md | モーションアニメーションの追加/編集 | 手動キーフレーム、アニメーション化された塗りつぶし/ストローク、アニメーションスタイルの適用、タイムライン期間 |
| motion-easing.md | アニメーションイージングの設定 | キーフレームイージングオブジェクト、カスタムcubic/spring、HOLD、アニメーションスタイル内でのイージングの適用 |
アニメーションの検証
get_screenshot はタイムラインの静止状態のみを表示し、モーションは決して表示しません。モーションを確認するには、export_video でフレームをサンプリングします。ただし、これはサーバーサイドでレンダリングされ、遅くてコストがかかる(約10秒〜数分) ため、各レンダリングを有効活用してください。
レンダリング前に計画を立ててください。コストはピクセル数×フレーム数に比例するため、両方を必要以上に大きくしないでください。
- まず瞬間を選びます。 スムーズな再生ではなく、フェーズごとに1フレーム必要です(例:スタッガーステップごと、または開始/中間/整定)。通常は4〜6フレームです。この数がfpsを決定します。
- 読み取る必要があるものにサイズを合わせます。 小さく始めてください —
constraint: { type: 'WIDTH', value: 320 }、quality: "low"— ただし、テキストや小さな要素はそこでぼやけるため、細かいディテールを判断する必要がある場合はWIDTHを上げてください(768+)。constraintを省略するとフルサイズ(1倍、サーバーは10倍/4096pxにクランプ)になります。 - それらのフレームを捉えるのに十分なだけ高いfpsを設定します:
fps: 5で数フレームに対応、10が上限です。それ以上にするとレンダリングが肥大化するだけです。
メカニズム: export_video は、子にアニメーションが含まれているトップレベルフレームでのみ機能します(キーフレームを設定した子孫ではなく、そのフレームを渡してください)。status: "processing" の jobId を返します — { fileKey, jobId } で再呼び出ししてポーリングします。その後、ローカルで ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png を使用してフレームを抽出します。抽出は無料なので、レンダリングにコストを払ったら、再エクスポートするのではなく、何かを教えてくれるすべてのフレームを活用してください。ffmpeg のようなフレーム抽出ツールがない場合は、エクスポートをスキップして、代わりにキーフレームについて推論してください。
正しくなるまで繰り返します。 エクスポートは診断であり、承認ではありません。フレームが間違っている場合(順序が悪い、タイミングがずれている、要素が欠けている、マスクでコンポジットが白くなる)、キーフレーム/スタイルを修正して再エクスポートしてください。すべてのフレームを読み、再レンダリングする前にすべての修正を1回のパスにまとめてください。すべてのレンダリングには実際のオーバーヘッドが伴うため、小さな変更のたびに再エクスポートするのではなく、各レンダリングを有効活用してください。
些細な変更や自明な変更の場合は、エクスポートを完全にスキップしてください。
プレフライトチェックリスト
figma-use プレフライトチェックリストに加えて、以下を確認してください。
- イージングは、内部のシーングラフ名(
OUT_CUBICなど)ではなく、公開された{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }形式を使用しています。 - イーズインアウトは、正確な公開enum
EASE_IN_AND_OUT(またはEASE_IN_AND_OUT_BACK)を使用しています。無効なエイリアスEASE_IN_OUTは決して使用しないでください。 - アニメーション化されるノードは、トップレベルフレーム(ページの直接の子)ではありません。代わりに子孫をアニメーション化してください。
- タイムライン値は、公開プラグインAPIの秒単位です。
setTimelineDurationで延長します。ユーザーが明示的に要求しない限り、短縮しないでください。 - トランスフォームキーフレームフィールドは、公開名(
TRANSLATION_X、TRANSLATION_Y、ROTATION、SCALE_X、SCALE_Y、SCALE_XY)を使用しています。内部のMOTION_*シーングラフ名は使用しないでください。 - 手動キーフレームフィールドは、motion-patterns.mdの公開許可リストから取得されます。生成された/内部のシーングラフフィールドは意図的にスローされます。
- ミューテーションされたノードIDが返されます(
figma-useルール15に従う)。 - モーションの正確性が自明でなく、フレーム抽出ツール(
ffmpeg)が利用可能な場合、export_video+ フレームサンプリングで検証します — 小さく、低いfpsでレンダリングし、正しくなるまで繰り返します(上記「アニメーションの検証」セクションを参照)。get_screenshotは静止状態のみを表示します。