モーションの実装
概要
このスキルは、Figmaのアニメーションとトランジションを実行可能なコード(motion.dev、CSSキーフレーム、またはフレームワーク固有のライブラリ)に変換するためのガイドです。
Figmaは2つのツールを通じてモーションを公開します:
get_motion_context— 信頼できるモーションツール。アニメーション化されたノードのインベントリ、事前計算されたコードスニペット(CSS@keyframes+ motion.dev)、スニペットが利用できない場合のフォールバックキーフレームバインディング、および再帰的なタイムライン調整のヒントを返します。アニメーションデータとどのノードIDがアニメーションするかに関する信頼できる情報源です。get_design_context— デザインの構造:レイアウト、サイズ、アセット、スタイリング、Code Connectのヒント、スクリーンショットコンテキスト、およびアニメーション要素上のモーションプレースメントマーカー(data-node-id、分割ノードではdata-motion-keys/data-motion-wrapper-for/data-motion-transform-template)を含む場合があります。アニメーション化されたノードをプレーンな要素(div、p、spanなど)またはモーション要素(motion.div)としてレンダリングする可能性がありますが、アニメーション値はインライン化しません。
この2つはノードIDによってリンクされており、これがワークフロー全体です。 get_motion_contextはどのノードがアニメーション化され、キーフレーム値、イージング、タイミング、スニペットを提供します。get_design_contextはそれらのノードがどのように見え、どこに配置されているかを示します。get_motion_context.nodesのすべてのノードについて、デザインコンテキスト内で一致するdata-node-idを見つけ、モーションをその構造にマージします。構造要素がプレーンな場合は、motion.{tag}を追加またはラップします。デザインコンテキストが再利用されたFigmaコンポーネントを使用している場合、モーションノードにはfallbackNodeIdも含まれる場合があります。これは、正確なnodeIdを試した後のフォールバックとしてのみ使用します。
スキルの境界
- 成果物がユーザーのリポジトリ内のモーションコードである場合にこのスキルを使用します。
- ユーザーがFigma自体でアニメーションを作成/編集するよう依頼した場合は、figma-useに切り替えてそのスキルに従います。
- このスキルは現在、
get_motion_contextによって出力されるアニメーション(スニペットとフォールバックキーフレームトラック、およびそれらの形式に解決されたプリセット作成モーションを含む)をカバーしています。より広範なインタラクティブバリアントフローでは、コード内で製品固有の状態処理が必要になる場合があります。
前提条件
- Figma MCPサーバーが接続され、アクセス可能であること。
- ユーザーが提供するFigma URLから解析されたノードID。URL形式:
https://figma.com/design/:fileKey/:fileName?node-id=1-2—fileKey(/design/の後のセグメント)とnodeId(node-idクエリパラメータの値、例:42-15)を抽出します。 - ターゲットコードベース。モーション出力形式はスタックに適応します(フレームワークの推奨事項を参照)。
ツールの選択
モーション実装では、異なる役割を持つ両方のツールを使用します:
| 状況 | ツール | 理由 |
|---|---|---|
| 静的な構造、アセット、スタイル、Code Connect、または視覚的なレイアウトを理解する | get_design_context | アニメーションノードを正しく配置するために必要なコンポーネント/ページコードリファレンスとアセットURLを提供します。 |
| 任意のノードのアニメーションデータを取得する | get_motion_context | モーション専用に構築されており、タイミング、イージング、スニペット、キーフレームの信頼できる情報源です。 |
ノードにモーションマーカーがある(data-motion-keys、data-motion-wrapper-for) | 分割配置のマーカー、値はget_motion_context | 分割マーカーはどのトラックがどの要素に属するかを示します。キーフレーム/イージング/タイミングとアニメーションノードのインベントリはget_motion_contextから取得します。 |
get_motion_contextは、子孫のモーションを一度の呼び出しで取得する必要がある場合に、recursive: true(最大500ノード)を受け入れます。
必要なワークフロー
ステップ 1:静的なデザインコンテキストが利用可能であることを確認する
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
get_design_contextがこのノードですでに呼び出されている場合は、その出力を再利用します。そうでない場合は、通常どおり呼び出します。
これを構造の記録として使用します — 階層、サイズ、スタイリング、アセット、Code Connectのヒント、スクリーンショットコンテキスト、および含まれている可能性のあるモーションプレースメントマーカー(ステップ3)。アニメーションノードのインベントリとアニメーション値はget_motion_context(ステップ2)から取得します。
ステップ 2:信頼できるモーションデータを取得する
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
応答の形状(アニメーションノードごとに1エントリ):
codeSnippets— 事前生成されたCSS@keyframesとmotion.dev文字列。これらを直接使用します。 フォールバックトラックデータから再生成しないでください。keyframeBindings— バインドされたキーフレームトラック。プリセットから派生したモーションがトラックデータに解決されたものを含み、両方のスニペット形式が欠落している場合のフォールバックデータとしてのみ含まれます。fallbackNodeId— コンポーネント化されたデザインコンテキストを一致させるためのオプションのフォールバックID。nodeIdがI4005:6111;30:8005のようなインスタンス修飾IDである場合、D2Rは代わりにバッキングコンポーネントID(4002:3957など)で再利用可能なコンポーネント本体をレンダリングする可能性があります。その場合、fallbackNodeIdは、正確なnodeIdルックアップが失敗した場合に検索するdata-node-idです。
再帰的な応答には、timelineCohortsも含まれる場合があります:同じタイムラインルート、期間、再生モード(once、loop、またはboomerang)を共有するアニメーションノードIDのグループ。コホートを使用して、兄弟の順序から共有タイミングを推測する代わりに、ずらしたり複数ノードのアニメーションを同期させます。
LLMにとって重要な実装の詳細:
- スニペットが存在する場合、生の
keyframeBindings、timelineDurationMs、motionSummary、デフォルトのtransformOriginは、ペイロードを小さく保つために削除される場合があります。keyframeBindingsが欠落していても、アニメーションがないというシグナルではありません。 - 再帰的な応答は、完全に重複するスニペットを重複排除します。スニペットは、同一のモーションを持つ最初のノードを指すコメントに置き換えられる場合があります。2番目のアニメーションを作成する代わりに、同じコンポーネント、バリアント、クラス、または定数を再利用します。
- MCPサーバーは
clientFrameworksからCSSスニペットとmotion.devスニペットを推測します。応答に1つのスニペット形式のみが含まれている場合は、他の形式が失敗したと想定するのではなく、その形式をユーザーのスタックに適応させます。
ステップ 3:静的コンテキストとモーションコンテキストをマージする
- 静的なJSX内の表示可能な
motion.*タグではなく、get_motion_context.nodesから開始します。返されるすべてのノードはアニメーション化されています。 各モーションノードを、最初に正確なnodeId/data-node-idでget_design_contextに一致させます。正確な一致がない場合にのみ、fallbackNodeId/data-node-idを試します。両方のIDが失敗した場合にのみ、ノード名/タイプとスクリーンショット位置にフォールバックします。 - 正確なID一致は
fallbackNodeIdよりも優先されます。fallbackNodeIdは、D2Rが再利用可能なコンポーネント内で出力する可能性のあるバッキングコンポーネントIDを指します。これはそのコンポーネントのすべてのインスタンスで共有されます。正確なnodeIdがデザインコンテキストに存在する場合は、そこにモーションを適用し、フォールバックを無視します。これはルートインスタンスアニメーションにとって重要です。1つのインスタンスは同じコンポーネントの別のインスタンスとは異なる方法で回転または移動する可能性があり、そのモーションを共有コンポーネント本体に適用すると、すべてのインスタンスが正しくアニメーションしなくなります。 - 各モーションノードを、
data-node-idをキーとして、一致するデザインコンテキスト構造に適用します。 一致するdata-node-idは構造アンカーであり、モーションを受け取る最終的なDOM要素であるとは限りません。スニペットの形状と配置マーカーを使用して、モーションをその正確な要素、ラッパー、内部要素、またはインライン化されたSVGパスのどこに配置するかを決定します。get_design_contextは、すでに値が取り除かれたmotion.{tag}を出力する場合もあれば、プレーンな構造要素(div、p、span、コンポーネントルートなど)を出力する場合もあります。それがプレーンで、スニペットが要素自体をターゲットにしている場合は、適切なmotion.{tag}に変換するか、ノードのテキスト、子、クラス/スタイル、属性、data-node-idを保持しながらモーションラッパーを追加します。このマージステップの例については、references/examples-and-anti-examples.mdを参照してください。 - コンポーネント化された子モーションは通常、フォールバックで一致します。 デザインコンテキストがFigmaインスタンスを再利用可能なReactコンポーネントに抽出する場合、そのコンポーネント本体の子はバッキングコンポーネントID(
4002:3957)を持つことが多く、モーションコンテキストはライブインスタンスID(I4005:6111;30:8005)を報告します。この場合、fallbackNodeIdを使用してコンポーネント本体のdata-node-idを見つけますが、モーションは実装中のレンダリングされたインスタンスにスコープされます。複数のインスタンスがあり、1つだけが異なるルートモーションを持つ場合、正確なIDマッチングによりそのインスタンスごとのモーションが分離されます。 - 分割ノードには
data-motion-keys/data-motion-wrapper-forマーカーがあります — 以下のインターリーブされたトランスフォームの処理を参照してください。 display: contentsラッパーを保持 — ただし、グループ自体がアニメーション化されている場合を除きます。 レイアウト透過的なグループラッパーはcontents(Tailwindcontents)として渡され、通常は無効なabsolute/inset-[…](これらはcontentsボックスでは何もしません)を伴います。静的グループの場合は、display: contentsを維持し、子を最も近い実際の祖先に対して配置します。ラッパーのinsetを配置されたボックスに変換すると、子がより小さなボックスに再ペアレント化されるため、小さく/内側にシフトしてレンダリングされます。アニメーション化されたグループ(グループノード自体にモーションがある)の場合、display: contentsはトランスフォームを伝達できません — 実際の配置されたラッパーに置き換え、グループモーションをそこに適用します。このケースを実装する前に、references/gotchas.mdを参照してください。get_motion_contextが完全なアニメーションノードインベントリです。 一部のアニメーションノードは、プレーンな(motionではない)要素 — コンポーネントインスタンスルート(プレーンな配置<div>)、テキスト(<p>)、マスク — としてレンダリングされ、それでもdata-node-idを持っています。モーション応答内のすべてのノードを確認し、一致するdata-node-idを持つ要素にモーションを適用し、必要に応じてラップまたは変換します。アニメーション化されたノードが出力にまったく要素を持たない場合(例えば、静的なmask-imageにフラット化されたアニメーションマスク)、黙って削除しないでください —// TODO: <nodeId> motion unsupportedコメントを残し、サマリーでそれを指摘します。- ノードがモーションコンテキストに現れるが静的なJSXには現れない場合は、それを表すために必要な要素を追加します。デザインコンテキストコードはリファレンスであり、完全なアニメーションインベントリではありません。
- デザインコンテキストとモーションコンテキストの間で競合がある場合(タイミング/イージング/アニメーション値)、
get_motion_contextを優先します。 - パスレベルのSVGモーション:SVGをインライン化し、実際の
<path>をアニメーション化します。get_motion_contextがベクターのパス(PATH_TRIM、motion.path、stroke-dasharray)をターゲットにしているが、デザインコンテキストが<img>としてレンダリングしている場合は、SVGをインライン化し、スニペットを<path>に適用し、レイアウトラッパーを保持します。このケースの完全な方法についてはreferences/svg-and-path-motion.mdを参照してください(motion.path、pathLength="1"、ラッパー+パスのレイヤリング、CSSパストリム)。
インターリーブされたトランスフォームの処理
静的ベーストランスフォームとアニメーショントランスフォームの両方を持つノードは、ネストされた要素に分割され、2つが競合する代わりに正しく合成されるようにします:data-motion-wrapper-for="<nodeId>"(OUTERラッパー)を運ぶIDなしのmotion.divが、静的トランスフォームdiv(例:rotate-45 + hypot()サイジング — またはラッパー自体がdata-motion-transform-template="<css>"を運ぶ)をラップし、それがINNERノード(data-node-id)をラップします。ラッパー > 静的トランスフォームdiv > 内部 のネストを維持します — それを崩すとサイジングとベーストランスフォームが壊れます。
data-motion-keysでトラックを配置します。 ラッパーのdata-motion-keys(トランスフォームトラック —x/y/rotate/scaleX/scaleY/skewX)はOUTERラッパーに配置されます。内部要素のdata-motion-keysはINNER要素に配置されます。data-motion-transform-templateを再適用します。 ラッパーが持っている場合、transformTemplate={(_, generated) => "<css> " + generated}を設定して、アニメーショントランスフォームがその静的レイアウトトランスフォームの上に合成されるようにします。- 静的ベースでアニメーショントランスフォームをオフセットします(二重回転を避ける)。
get_motion_contextはノードの絶対トランスフォームを提供します。これはすでにそれらのdivが適用する静的なベースを含んでいます。rotate-45ベース上の[45, 125, 125]のrotateスニペットは、ラッパーがオフセット[0, 80, 80](= 絶対 − 45)をアニメーション化することを意味し、絶対値ではありません — そうしないと45°が2回適用され、要素は静止時に90°になります。静的ベースのないトラック(例:0から始まるx/y)は変更されずに通過します。インターリーブトランスフォームの例を参照してください。 - レイアウトトランスフォームをモーショントランスフォームから分離します。
rotate、scale、またはskewをアニメーション化するすべてのmotion.*要素について、それがセンタリング/ポジショニングのためにTailwindレイアウトトランスフォーム(-translate-x-1/2や-translate-y-1/2など)にも依存していないことを確認します。これらのユーティリティは、Motion.devがインラインで書き込むCSStransformプロパティを共有するため、Motionのトランスフォームがレイアウトトランスレートを消去する可能性があります。両方必要な場合は、要素を、センタリング/ポジショニングトランスフォームを運ぶ静的レイアウトラッパーと、アニメーション化された回転/スケール/不透明度を運ぶ内部のmotion.*要素に分割するか、レイアウトオフセットをMotion自体(x: "-50%")にエンコードし、すべてのキーフレームでそれを維持します。
ステップ 4:コードにモーションを適用する
- スニペットにmotion.devが存在する? Reactターゲットにはmotion.devコードをそのまま使用します。
motion/reactからインポートします — ただし、コードベースがすでに別のモーションライブラリ(Framer Motion、React Spring、GSAP)を使用している場合は、スニペットをそれに適応させます。別のスタックに適応させる場合やライブラリを選択する場合は、references/framework-recommendations.mdを参照してください。 - CSSキーフレームが存在する? バニラ/非Reactターゲット、またはコードベースにReactモーションライブラリがない場合に使用します。
- スニペットがない?
keyframeBindingsまたはmotionSummaryをフォールバックデータとして使用して、同等のmotion.dev呼び出しまたはCSSキーフレームを構築します。通常はスニペットが存在します。両方のスニペット形式が本当に欠落している場合にのみこれを行います。
ステップ 5:検証する
- 新しいものを追加する前に、コンポーネントの既存のモーションインポート/規則を読み取ります。ユーザーがすでにFramer Motion / React Spring / anime.jsを使用している場合は、motion.devを強制するのではなく適応させます。
- 多くのノードにわたって変更をバッチ処理する前に、1つのアニメーションがエンドツーエンドで実行されることをスポットチェックします(リロード、観察、反復)。
- references/gotchas.mdを実装前に参照します。
- 実装が不完全な場合やトレードオフがある場合は、明確なTODOコメントとサマリーを残します。