use_figma — モーションのためのFigma Plugin APIスキル
use_figma MCPツールのモーションコンテキストです。figma-useが基礎となるPlugin APIルールをカバーしているため、両方を一緒に読み込んでください。
モーションワークで use_figma を呼び出すときは、常に skillNames: "figma-use-motion" を(figma-use とカンマ区切りで)渡してください。 ログのみです。
ランタイムゲート
モーションAPIは、ユーザー機能フラグ metronome_plugin_api の背後にゲートされています。呼び出し元のユーザーがこのフラグを持っていない場合、このスキルで参照されるすべてのモーションプロパティとヘルパーは "<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 | アニメーションイージングの設定時 | キーフレームイージングオブジェクト、カスタムキュービック/スプリング、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?: … }の形状を使用しています。 - イーズインアウトは、正確な公開列挙型
EASE_IN_AND_OUT(またはEASE_IN_AND_OUT_BACK)を使用しています。無効なエイリアスEASE_IN_OUTは絶対に使用しないでください。 - アニメーション化されているノードはトップレベルフレーム(ページの直接の子)ではありません。代わりに子孫をアニメーション化してください。
- タイムライン値は公開Plugin APIの秒単位です。
setTimelineDurationで延長します。ユーザーが要求しない限り、短縮しないでください。 - トランスフォームキーフレームフィールドは、内部の
MOTION_*シーングラフ名ではなく、公開名(TRANSLATION_X、TRANSLATION_Y、ROTATION、SCALE_X、SCALE_Y、SCALE_XY)を使用しています。 - 手動キーフレームフィールドは、motion-patterns.mdの公開許可リストから取得されています。生成された/内部のシーングラフフィールドは意図的にスローされます。
- 変更されたノードIDが返されています(
figma-useルール15に従う)。 - モーションの正確性が自明でなく、フレーム抽出ツール(
ffmpeg)が利用可能な場合は、export_video+ フレームサンプリングで検証します。小さく、低いfpsでレンダリングし、正しくなるまで反復します(上記の「アニメーションの検証」セクションを参照)。get_screenshotは静止状態のみを表示します。