figma-use-motion

use_figma — Motion 向け Figma Plugin API スキル

use_figma MCP ツールの Motion コンテキストです。figma-use では基礎となる Plugin API のルールを説明しています。両方を一緒に読み込んでください。

Motion 関連の作業で use_figma を呼び出すときは、必ず skillNames: "figma-use-motion" を指定してください（figma-use と併せてカンマ区切りで指定）。 ログ記録のみです。

ランタイムの制限

呼び出し元のユーザーに Motion API が有効になっていない場合があります。利用できないときは、このスキルで参照するすべての Motion プロパティとヘルパーが "<name>" is not a supported API をスローします。

このエラーが発生したら、すぐに中止してください。 再試行せず、ユーザーに Motion が有効になっていないことを伝えて終了してください。そうしないと、呼び出しを浪費し、同じエラーを繰り返すことでユーザーを混乱させてしまいます。

他の Motion API が動作していても、カスタムアニメーションスタイルが有効になっていない場合があります。利用可否の確認方法とフォールバックのガイダンスについては、motion-custom-styles.md を参照してください。

TextStagger を適用する前に、figma.motion.figmaAnimationStyles() で見つけてください。存在しない場合は、このセッションではテキストの Motion が利用できないことを説明してください。検出を回避したり、レイヤー全体の Motion に黙って置き換えたりしないでください。

このスキルを使う場面

use_figma のタスクに次の内容が含まれる場合は、このスキルを読み込んでください。

• ノードのキーフレームの追加、編集、削除（manualKeyframeTracks、applyManualKeyframeTrack、removeManualKeyframeTrack）。
• 時間経過に伴う塗りや線の色のアニメーション。
• アニメーションスタイルの適用、編集、削除（applyAnimationStyle、removeAnimationStyle、animationStyles）。
• ローカルカスタムアニメーションスタイル（ファイルに保存される再利用可能な名前付き Motion スタイル）の検出、作成、編集、整理、適用、削除（figma.getLocalCustomAnimationStylesAsync、figma.createCustomAnimationStyle）。
• 編集可能なテキスト内の文字、単語、行、段落のアニメーション。タイプライター表示や、テキストアニメーション内のスタイル編集も含みます。書き込む前に text-animation.md を読み込んでください。
• node.timelines / node.setTimelineDuration(id, seconds) によるタイムラインの長さの読み取りまたは書き込み。
• 上記のいずれかにおけるイージングの選択。

静的なデザイン作業（図形、コンポーネント、変数、レイアウトの作成）は figma-use のみで行います。このスキルは時間軸に関する作業専用です。

公開されている Motion API

• node.manualKeyframeTracks — 手動キーフレーム（塗り、線、エフェクトのトラックを含む）の読み取りと書き込み。
• node.applyManualKeyframeTrack(field, track) / node.removeManualKeyframeTrack(field) — オブジェクト全体を書き換えずに、手動キーフレームトラックを追加、置換、削除。
• 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 標準のアニメーションスタイル定義一覧を読み取り専用で取得。
• カスタムアニメーションスタイルの操作に利用できる各種 API については、motion-custom-styles.md を参照してください。

カスタム "figma:motion" プリセットモジュールのソースコード作成は対象外です。検出済みの TextStagger 内で Position、Rotation、Scale、Opacity、Blur の各スタイルを設定することはサポートされています。これらは単一のネイティブプリセットのプロパティであり、新しいプリセットのソースコードではありません。新しいプリセットモジュールの作成が必要なリクエストの場合は、その制約を説明してください。作り上げてはいけません。

参考ドキュメント

作業内容に応じて、必要なドキュメントを読み込んでください。

ドキュメント	読み込むタイミング	内容
motion-patterns.md	モーションアニメーションを追加・編集するとき	手動キーフレーム、塗りや線のアニメーション化、アニメーションスタイルの適用、タイムラインの長さ
motion-custom-styles.md	再利用可能な名前付きモーションスタイルを扱うとき	ローカルのカスタムアニメーションスタイルの確認、作成、編集、整理、適用、削除、検証
text-animation.md	テキストのリビール、タイプライター効果、または段階的に表示するテキストを作成・編集するとき	ネイティブの TextStagger、グループ化と順序、組み合わせたテキストスタイル、タイミング、編集と削除、編集可能なテキストの保持
motion-easing.md	アニメーションのイージングを設定するとき	キーフレームのイージングオブジェクト、カスタムのキュービック／スプリング、HOLD、アニメーションスタイル内でのイージングの適用

アニメーションの検証

get_screenshot で確認できるのはタイムラインの静止状態のみで、モーションは確認できません。モーションを確認するには、export_video で動画を出力し、フレームをサンプリングします。ただし、サーバー側でレンダリングされるため、時間もコストもかかります（約10秒から数分）。そのため、レンダリング1回あたりの情報量を最大限にしてください。

レンダリング前に計画してください。コストはピクセル数×フレーム数に応じて増えるため、どちらも必要最小限に抑えます。

1. 先に確認するタイミングを選びます。 滑らかな再生ではなく、各フェーズにつき1フレームが必要です（段階表示の各ステップ、または開始／中間／停止時など）。通常は4～6フレームです。この枚数を基にfpsを設定します。
2. 読み取る必要がある内容に合わせてサイズを決めます。 まずは小さく始めます（constraint: { type: 'WIDTH', value: 320 }、quality: "low"）。ただし、このサイズではテキストや小さな要素がぼやけるため、細部を判断する必要がある場合は WIDTH を大きくします（768以上）。constraint を省略するとフルサイズになります（1x。サーバー側で最大10x／4096pxに制限されます）。
3. 必要なフレームを取得できる最低限の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 を使って延長してください。ユーザーから依頼がない限り、短縮しないでください。
• テキスト内のモーションには、既存のテキストノード上で検出済みの TextStagger を使用してください。文字、書式、折り返し、無関係なアニメーションはそのまま維持してください。duration は文字ごとの時間ではなく、スタガー全体の長さです。
• 変換キーフレームのフィールドには、内部の 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 では静止状態しか確認できません。