モーションの実装
概要
このスキルは、Figma アニメーションとトランジションを実行可能なコード(motion.dev、CSS @keyframes、またはフレームワーク固有のライブラリ)に変換する方法を説明します。
Figma は2つのツールを通じてモーションを公開します:
get_motion_context— 信頼できるモーションツール。アニメーション化されたノードの完全なインベントリ、事前計算されたコードスニペット(CSS@keyframes+ motion.dev)、スニペットが利用できない場合のフォールバックキーフレームバインディング、および再帰的なタイムライン調整ヒント(timelineCohorts)を返します。アニメーションデータとどのノード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 は、1回の呼び出しで子孫のモーションを取得する必要がある場合に 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— バインドされたキーフレームトラック。プリセットから派生したモーションがトラックデータに解決されたものを含み、両方のスニペット形式が欠落している場合のフォールバックデータとしてのみ含まれます。motionSummary— アニメーションの1行1フィールドの自然言語での説明。スニペットがない場合にのみ存在します(キーフレームバインディングのみのモーションコード生成がCSS/motion.devで表現できなかった場合)。存在する場合はそこから構築します。スニペットが存在する場合は無視します。fallbackNodeId— コンポーネント化されたデザインコンテキストと一致させるためのオプションのフォールバックID。nodeIdがI4005:6111;30:8005のようなインスタンス修飾IDである場合、D2Rは代わりに4002:3957のようなバッキングコンポーネントIDで再利用可能なコンポーネント本体をレンダリングする可能性があります。その場合、fallbackNodeIdは、正確なnodeIdのルックアップが失敗した場合に探すべきdata-node-idです。
再帰的な応答には timelineCohorts も含まれます — これはトップレベルの配列(ノードごとではない)で、1つのタイムラインを共有するノードのグループです: { rootNodeId, durationMs, loopMode: 'once' | 'loop' | 'boomerang', memberNodeIds[] }。調整されたマルチノードモーションの場合、durationMs(÷1000で秒単位)と loopMode を使用して、すべての memberNodeIds を1つの共有ライフサイクルから駆動します — タイミングを兄弟の順序から推測しないでください。
LLMにとって重要な実装の詳細:
- スニペットが存在する場合、
motionSummary、timelineDurationMs、およびtransformOriginはペイロードを縮小するために省略される場合があります — スニペットはすでに duration + transform-origin(motion.dev のduration/style={{ transformOrigin }}、または CSS のanimation/transform-origin)を保持しており、コーホートはdurationMsを保持します。フィールドが欠落しているからといって「アニメーションなし」を意味するわけではありません。 - 再帰的な応答は、重複する同一のスニペットを除外します。スニペットは、同一のモーションを持つ最初のノードを指すコメントに置き換えられる場合があります。2番目のアニメーションを記述する代わりに、同じコンポーネント、バリアント、クラス、または定数を再利用します。
- MCP サーバーは
clientFrameworksから CSS vs motion.dev スニペットを推測します。応答に1つのスニペット形式のみが含まれている場合は、他の形式が失敗したと想定するのではなく、その形式をユーザーのスタックに適応させます。
ステップ 3: 静的コンテキストとモーションコンテキストのマージ
get_design_contextの可視の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(Tailwind のcontents)として渡されます。通常、無効な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> モーション未サポートコメントを残し、サマリーでそれを指摘します。- ノードがモーションコンテキストに現れるが静的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つが競合する代わりに正しく合成されるように、ネストされた要素間で分割されます: IDのない data-motion-wrapper-for="<nodeId>" を持つ motion.div(外部ラッパー)が静的変換div(例: rotate-45 + hypot() サイズ設定 — またはラッパー自体が data-motion-transform-template="<css>" を持つ)をラップし、それが内部ノード(data-node-id)をラップします。wrapper > static-transform div > inner のネストを保持します — それを崩すとサイズ設定とベース変換が壊れます。
data-motion-keysでトラックを配置します。 ラッパーのdata-motion-keys(変換トラック —x/y/rotate/scaleX/scaleY/skewX)は外部ラッパーに配置します。内部要素のdata-motion-keysは内部要素に配置します。data-motion-transform-templateを再適用します。 ラッパーが1つ持っている場合は、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.*要素について、中央揃え/配置のために-translate-x-1/2や-translate-y-1/2などのTailwindレイアウト変換にも依存していないことを確認します。これらのユーティリティはCSStransformプロパティを共有し、Motion.devはそれをインラインで書き込むため、Motionの変換によってレイアウトの移動が消去される可能性があります。両方が必要な場合は、中央揃え/配置変換を運ぶ静的なレイアウトラッパーと、アニメーション化されたrotate/scale/opacityを運ぶ内部のmotion.*要素に要素を分割するか、レイアウトオフセットをMotion自体(x: "-50%")にエンコードし、すべてのキーフレームに対してそれを存在させ続けます。
ステップ 4: コードにモーションを適用
- motion.dev がスニペットに存在しますか? Reactターゲットの場合は motion.dev コードをそのまま使用します。インポートは
motion/reactから行います — ただし、コードベースがすでに別のモーションライブラリ(Framer Motion、React Spring、GSAP)を使用している場合は除きます。その場合はスニペットをそれに適応させます。別のスタックに適応する場合やライブラリを選択する場合は、references/framework-recommendations.md を読み込んでください。 - CSS @keyframes が存在しますか? バニラ/非Reactターゲット、またはコードベースにReactモーションライブラリがない場合に使用します。
- スニペットなし(キーフレームバインディングのみ)? ライブラリのAPIを使用して
keyframeBindingsから同等の motion.dev/CSS を構築します。ターゲットが motion.dev の場合、animate関数を使用して、各バインディングのキーフレームとイージングを渡します。CSSターゲットの場合、@keyframesを直接記述するか、animationショートハンドプロパティを使用します。 - スニペット内のターゲットタグに注意してください。
motion.divは<div>要素のアニメーション用、motion.pathはSVG<path>要素用、その他同様です。codeSnippets.motionDotからのタグはスニペット自体に埋め込まれています — 出力の適切な要素に適用してください。 - タイムラインコーホートを実装します。
timelineCohorts配列内の各コーホートについて、コーホートのmemberNodeIds内のすべてのノードを、durationMsと同じ継続時間を持つ単一のアニメーション駆動またはタイムラインにグループ化します。コーホートは単一のルートノードによって所有され、rootNodeIdをマークします。コーホート内のノードは、個別の独立したタイミングを持つのではなく、共有タイムライン上で再生されます。
コーホート実装のガイドライン
- コーホート内の各ノードは個別のエントリとして
get_motion_context.nodesに存在し、それぞれ独自のスニペットまたはキーフレームバインディングを持ちます。各ノードのアニメーションを個別に実装しますが、durationMsを使用してすべてを同じ長さにします。親コーホートの継続時間を超えるノードはありません(Figmaはそれを許可しません)。 - motion.dev の場合、すべてのメンバーノードを
useAnimateでラップし、それらを単一のアニメーション呼び出しとしてグループ化するか、各メンバーを同じdurationで個別にアニメーション化します。 - CSS の場合、すべてのメンバーノードを同じ
animation-durationで宣言します。 - コーホートのループ動作を尊重します:
loopMode: 'loop'は無限にループします。loopMode: 'once'は1回再生されます。loopMode: 'boomerang'は forward + backward = 1回の完全なサイクルとしてアニメーション化します。
フレームワークの推奨事項
デフォルト: motion.dev(React)
- ライブラリが指定されていないReactコードベースに推奨されます。
npm install motionimport { motion, AnimatePresence, useAnimate } from 'motion/react'durationは motion.dev では秒単位であり、get_motion_contextはミリ秒単位であることに注意してください。スニペットはすでに正しい単位で表現されています。スニペットがない場合は、durationMs / 1000で変換します。
motion.dev(Svelte)
import { motion } from 'motion/svelte'
motion.dev(Vue)
npm install motion-vueimport { motion } from 'motion-vue'
motion.dev(Solid)
npm install motion-solidimport { motion } from 'motion-solid'
motion.dev(Lit)
import { motion } from 'motion/lit'
バニラCSS / 他のフレームワーク
- バニラCSSターゲット、またはコードベースにReactモーションライブラリがない場合に使用します。
get_motion_context.codeSnippets.cssKeyframesを抽出し、それを<style>ブロックまたはCSSファイルに配置し、生成されたクラス名をHTML要素に割り当てます。
Framer Motion
- 既存のコードベースがFramer Motionを使用している場合に使用します。
codeSnippets.motionDot(motion.dev スニペット)を Framer Motion の構文に変換します。- motion.dev と Framer Motion は
motionコンポーネントを共有しますが、アニメーションAPIは異なります。- motion.dev の
useAnimateと Framer Motion のuseAnimateは異なるシグネチャを持ちます。 - motion.dev は宣言的アニメーションに
initial+animateを、Framer Motion はinitial+animate+transitionを使用します。
- motion.dev の
- 変換が必要です。
- Framer Motion アニメーションの実装を完了するには、
get_motion_context.keyframeBindingsのキーフレームバインディングにアクセスする必要がある場合があります。 - 以下のセクション『スニペットがない場合のキーフレームバインディングの使用』に従って、キーフレームバインディングを Framer Motion 構文に変換する方法のガイダンスを確認してください。
スニペットがない場合のキーフレームバインディングの使用
スニペットが存在しない場合は、keyframeBindings からアニメーションを構築します。
// keyframeBindings の形状の例
{
"translateX": {
"keyframes": [0, 100, 200],
"timing": [0, 0.5, 1], // 0〜1の正規化されたタイミング
"easing": ["easeInOut", "easeOut"] // 各セグメントのCSSイージング
},
"rotate": {
"keyframes": [0, 45],
"timing": [0, 1],
"easing": ["easeOut"]
}
}
keyframeBindings からの motion.dev
motion.dev でキーフレームバインディングを使用するには、animate 関数を使用します:
import { animate } from 'motion/react';
const controls = animate(
elementRef,
{
x: [0, 100, 200], // translateX
rotate: [0, 45],
},
{
duration: 0.5, // ミリ秒を秒に変換 (500ms)
ease: ['easeInOut', 'easeOut'],
// タイミング配列が[0, 0.5, 1]の場合、中間キーフレームを50%マークに配置
// motion.devはデフォルトでスペーシングを均等にしません —
// 代わりに `offset` プロパティを使用
offset: [0, 0.5, 1],
}
);
motion.dev ノート:
offsetは各キーフレームの位置を定義するために重要です。これはtiming配列に直接対応します。easeはセグメントごとに指定され、timingよりも1つ少ない要素を持ちます。- motion.dev の
durationは秒単位です(get_motion_context の値がミリ秒の場合は変換)。
keyframeBindings からの CSS
CSSでキーフレームバインディングを使用するには、@keyframes ルールを構築します:
@keyframes slide-and-rotate {
0% {
transform: translateX(0px) rotate(0deg);
}
50% {
transform: translateX(100px) rotate(22.5deg);
}
100% {
transform: translateX(200px) rotate(45deg);
}
}
.element {
animation-name: slide-and-rotate;
animation-duration: 500ms;
animation-timing-function: ease-in-out; /* Note: CSSではセグメントごとのイージングのサポートが限られています */
animation-fill-mode: forwards;
}
CSS ノート:
- CSS
@keyframesは通常、単一のタイミング関数を全体に適用するか、セグメントごとに異なるanimation-timing-functionを@keyframes内のパーセンテージルールに適用します。easing配列が複数の値を持つ場合は、各キーフレームパーセンテージに個別のanimation-timing-functionを設定します(CSSではanimation-timing-functionはキーフレームセレクタ内に配置して、_次の_セグメントのイージングを制御できます)。 timing配列はキーフレームパーセンテージに直接マッピングされます。
keyframeBindings からの Framer Motion
<motion.div
animate={{
x: [0, 100, 200],
rotate: [0, 45],
}}
transition={{
duration: 0.5,
ease: ['easeInOut', 'easeOut'],
times: [0, 0.5, 1],
}}
/>
コードサンプル
以下に、get_motion_context と get_design_context の出力をマージする方法の完全な例を示します。
前提条件からの例
デザインコンテキスト(get_design_context から):
<div className="relative w-full h-64 bg-gray-100 rounded-lg overflow-hidden">
<div
data-node-id="1234:56"
className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-20 h-20 bg-blue-500 rounded-full"
/>
</div>
モーションコンテキスト(get_motion_context から):
{
"nodes": [
{
"nodeId": "1234:56",
"codeSnippets": {
"motionDot": "<motion.div animate={{ x: [0, 100, 0], rotate: [0, 360, 0] }} transition={{ duration: 2, repeat: Infinity }} />",
"cssKeyframes": "@keyframes slide-rotate { 0% { transform: translateX(0px) rotate(0deg); } 50% { transform: translateX(100px) rotate(180deg); } 100% { transform: translateX(0px) rotate(360deg); } }"
},
"keyframeBindings": {
"translateX": { "keyframes": [0, 100, 0], "timing": [0, 0.5, 1], "easing": ["easeInOut", "easeInOut"] },
"rotate": { "keyframes": [0, 360, 0], "timing": [0, 0.5, 1], "easing": ["easeInOut", "easeInOut"] }
}
}
],
"timelineCohorts": []
}
マージされたコード(スニペットを使用):
get_motion_context.codeSnippets.motionDot が利用可能で、コードベースが motion.dev を使用しているため、スニペットを使用し、get_motion_context から get_design_context 構造にマージします:
import { motion } from 'motion/react';
<div className="relative w-full h-64 bg-gray-100 rounded-lg overflow-hidden">
<motion.div
data-node-id="1234:56"
className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-20 h-20 bg-blue-500 rounded-full"
animate={{ x: [0, 100, 0], rotate: [0, 360, 0] }}
transition={{ duration: 2, repeat: Infinity }}
/>
</div>
get_design_context からの構造は保持され、モーションアニメーションで拡張されています。-translate-x-1/2 と -translate-y-1/2 はMotionの x と rotate のアニメーションと競合するため、これらのレイアウト変換を処理するための静的ラッパーで囲み、モーションを保持することを検討する必要があります:
import { motion } from 'motion/react';
<div className="relative w-full h-64 bg-gray-100 rounded-lg overflow-hidden">
<div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">
<motion.div
data-node-id="1234:56"
className="w-20 h-20 bg-blue-500 rounded-full"
animate={{ x: [0, 100, 0], rotate: [0, 360, 0] }}
transition={{ duration: 2, repeat: Infinity }}
/>
</div>
</div>
インターリーブ変換の例
デザインコンテキスト:
<div data-node-id="7890:12">
<div
data-motion-wrapper-for="7890:12"
data-motion-keys="x|y|rotate|scaleX|scaleY|skewX"
data-motion-transform-template="translate(-50%, -50%) {transform}"
>
<div className="rotate-45">
<div
data-node-id="7890:12"
data-motion-keys=""
className="w-20 h-20 bg-blue-500"
/>
</div>
</div>
</div>
モーションコンテキスト:
{
"nodeId": "7890:12",
"codeSnippets": {
"motionDot": "<motion.div animate={{ rotate: [45, 125, 45], x: [0, 50, 0] }} transition={{ duration: 1 }} />"
},
"keyframeBindings": {
"rotate": { "keyframes": [45, 125, 45], "timing": [0, 0.5, 1], "easing": ["easeInOut", "easeInOut"] },
"x": { "keyframes": [0, 50, 0], "timing": [0, 0.5, 1], "easing": ["easeInOut", "easeInOut"] }
}
}
分析: ノード 7890:12 には、静的ベース(rotate-45、レイアウト translate(-50%, -50%))とアニメーション(rotate: [45, 125, 45] + x: [0, 50, 0])の両方があります。静的ベースはすでに絶対回転値に寄与しているため、二重回転を避けるためにアニメーションをオフセットする必要があります。絶対 rotate 値は [45, 125, 45]、静的 rotate-45 は45°、オフセットは [0, 80, 0] です。x は静的ベースがないためオフセットされません。
マージされたコード:
import { motion } from 'motion/react';
<div data-node-id="7890:12">
<motion.div
data-motion-wrapper-for="7890:12"
data-motion-keys="x|y|rotate|scaleX|scaleY|skewX"
data-motion-transform-template="translate(-50%, -50%) {transform}"
animate={{ rotate: [0, 80, 0], x: [0, 50, 0] }}
transition={{ duration: 1 }}
transformTemplate={(_, generated) => `translate(-50%, -50%) ${generated}`}
>
<div className="rotate-45">
<div
data-node-id="7890:12"
data-motion-keys=""
className="w-20 h-20 bg-blue-500"
/>
</div>
</motion.div>
</div>
重要なポイント:
- アニメーション変換(
x、rotate)は外部motion.divラッパーに適用され、ラッパーのdata-motion-keysと一致します。 静的rotate-45とレイアウトtranslateは中間divに残ります。 transformTemplateは、アニメーション変換を静的なtranslate(-50%, -50%)の上に合成するために使用され、data-motion-transform-templateに従います。rotateアニメーションは[0, 80, 0]にオフセットされ([45, 125, 45]- 静的45°)、rotate-45divが45°の静的ベースを処理するため、二重適用を防ぎます。 デフォルトのtransformTemplateが外部ラッパーのアニメーションだけを考慮する場合、rotateの静的45°はすでに存在するため、アニメーションはオフセットして静的ベースの上に合成する必要があります。xはオフセットされません。静的ベースのxはありません。data-motion-keys=""の内部ノードは、この場合アニメーションを直接持ちません。
コンポーネント化された子モーションの例
デザインコンテキスト(get_design_context から):
// 呼び出し側
<Card icon={<Icon iconId="star" />} title="Hello" />
// Cardコンポーネント
function Card({ icon, title }) {
return (
<div className="card">
<div data-node-id="4002:3957" className="icon-wrapper">
{icon}
</div>
<h3>{title}</h3>
</div>
);
}
モーションコンテキスト(get_motion_context から):
{
"nodes": [
{
"nodeId": "I4005:6111;30:8005",
"fallbackNodeId": "4002:3957",
"codeSnippets": {
"motionDot": "<motion.div animate={{ rotate: [0, 360] }} transition={{ duration: 1, repeat: Infinity }} />"
},
"keyframeBindings": {}
}
]
}
分析: モーションコンテキストの nodeId は I4005:6111;30:8005(ライブインスタンスID)であり、デザインコンテキストには data-node-id="4002:3957"(バッキングコンポーネントID)の要素があります。fallbackNodeId の 4002:3957 は、data-node-id="4002:3957" と一致します。これにより、子モーションを Card コンポーネント本体内の .icon-wrapper 要素に適用できるようになります。fallbackNodeId は、ルックアップに失敗した場合のフォールバックとしてのみ使用され、使用されたとしても、この <Card /> インスタンスにスコープされたモーションを維持します。この場合、data-node-id は 4002:3957 で、fallbackNodeId を使用して正常に見つかりました。
マージされたコード(Cardコンポーネント内):
import { motion } from 'motion/react';
function Card({ icon, title }) {
return (
<div className="card">
<motion.div
data-node-id={/* マージ後: 4002:3957 */}
className="icon-wrapper"
animate={{ rotate: [0, 360] }}
transition={{ duration: 1, repeat: Infinity }}
>
{icon}
</motion.div>
<h3>{title}</h3>
</div>
);
}
重要なポイント: fallbackNodeId を使用してコンポーネント本体の data-node-id を特定しましたが、モーションはこの <Card /> インスタンスのレンダリングにのみ適用されます。Cardコンポーネントが複数回使用される場合、他のインスタンスはこのアニメーションを継承しません。
display: contents の処理例
静的グループ(display: contents を保持)
デザインコンテキスト:
<div data-node-id="1111:22">
{/* 静的グループラッパー — これはアニメーション化されていません */}
<div className="contents absolute inset-0">
<div className="w-10 h-10 bg-red-500" />
<div className="w-10 h-10 bg-blue-500" />
</div>
</div>
正しい処理: グループは静的であるため、display: contents を保持しても問題ありません。子要素は最も近い実際の祖先に対して配置されます。absolute / inset-0 クラスは contents ボックスでは効果がありませんが、そのままにしておいても安全です。
アニメーション化されたグループ(display: contents を配置されたラッパーに置き換え)
モーションコンテキスト(アニメーション化されたグループの場合):
{
"nodes": [
{
"nodeId": "1111:22",
"codeSnippets": {
"motionDot": "<motion.div animate={{ scale: [1, 1.2, 1] }} transition={{ duration: 0.5 }} />"
}
}
]
}
正しい処理: グループノード 1111:22 はアニメーション化されているため、display: contents は変換を伝達できません。ラッパーを実際に配置された要素に置き換え、グループモーションを適用します:
import { motion } from 'motion/react';
<div data-node-id="1111:22">
<motion.div
className="absolute inset-0" // 'contents' を 'absolute inset-0' に置き換え
animate={{ scale: [1, 1.2, 1] }}
transition={{ duration: 0.5 }}
>
<div className="w-10 h-10 bg-red-500" />
<div className="w-10 h-10 bg-blue-500" />
</motion.div>
</div>
レイアウトとアニメーションの競合の例
問題のあるケース(-translate-x-1/2 がMotionの rotate と競合)
デザインコンテキスト:
<div
data-node-id="9999:88"
className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-10 h-10 bg-green-500"
/>
モーションコンテキストが rotate をアニメーション化する場合:
{
"nodeId": "9999:88",
"codeSnippets": {
"motionDot": "<motion.div animate={{ rotate: [0, 45, 0] }} transition={{ duration: 1 }} />"
}
}
問題: -translate-x-1/2 と -translate-y-1/2 はCSSの transform プロパティを使用しており、Motionが rotate のためにインラインで transform を書き込むと、そのレイアウト変換が上書きされ、要素が中央から外れます。
解決策: 静的ラッパー
import { motion } from 'motion/react';
<div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">
<motion.div
data-node-id="9999:88"
className="w-10 h-10 bg-green-500"
animate={{ rotate: [0, 45, 0] }}
transition={{ duration: 1 }}
/>
</div>
これで、レイアウト変換(中央揃え)は外部ラッパーに、アニメーション変換は内部の motion.div に分離されました。
別の解決策: Motion内でレイアウトをエンコード
すべてのキーフレームに x: "-50%" を追加する:
<motion.div
data-node-id="9999:88"
className="absolute top-1/2 left-1/2 w-10 h-10 bg-green-500"
animate={{ rotate: [0, 45, 0], x: "-50%", y: "-50%" }}
transition={{ duration: 1 }}
/>
両方の解決策が有効です。デザインの構造に応じて適切な方を選択してください。
未サポートのモーションノートの例
デザインコンテキストがアニメーション化されたマスクを mask-image に平坦化する場合:
モーションコンテキスト:
{
"nodes": [
{
"nodeId": "5555:66",
"codeSnippets": {
"cssKeyframes": "@keyframes mask-anim { 0% { mask-image: url(a.svg); } 100% { mask-image: url(b.svg); } }"
}
}
]
}
デザインコンテキストがマスクを画像としてレンダリングする場合:
<div data-node-id="5555:66" className="mask-image: url(a.svg)" />
正しい処理: マスクは静的なものとしてレンダリングされます。その data-node-id を持つ要素はありますが、アニメーションは適用できません。正しい動作は、コメントを残してサマリーで報告することです:
<div data-node-id="5555:66" className="mask-image: url(a.svg)" />
{/* TODO: 5555:66 モーション未サポート — マスクアニメーションは mask-image として平坦化されています */}
サマリーで「ノード 5555:66 はアニメーション化されていますが、そのマスクアニメーションは現在のデザインコンテキストではサポートされていません。」と述べます。
スニペットから構築する場合とキーフレームバインディングから構築する場合
ケース1: スニペットが利用可能
codeSnippets が利用可能な場合は、常に codeSnippets を選択します。これは keyframeBindings よりも優先されます。
ケース2: スニペットがない — keyframeBindings からの構築
codeSnippets が利用できない場合は、keyframeBindings を使用してアニメーションを構築します。以下は、keyframeBindings を motion.dev、CSS、または Framer Motion に変換する方法の例です:
keyframeBindings から motion.dev:
import { animate } from 'motion/react';
const elementToAnimate = document.getElementById('myElement');
const controls = animate(
elementToAnimate,
{
x: [0, 100, 0],
rotate: [0, 360, 0],
},
{
duration: 2,
ease: ['easeInOut', 'easeInOut'],
offset: [0, 0.5, 1],
repeat: Infinity,
}
);
keyframeBindings から CSS:
@keyframes slide-rotate {
0% {
transform: translateX(0px) rotate(0deg);
}
50% {
transform: translateX(100px) rotate(180deg);
}
100% {
transform: translateX(0px) rotate(360deg);
}
}
.my-element {
animation-name: slide-rotate;
animation-duration: 2s;
animation-timing-function: ease-in-out;
animation-iteration-count: infinite;
}
keyframeBindings から Framer Motion:
<motion.div
animate={{
x: [0, 100, 0],
rotate: [0, 360, 0],
}}
transition={{
duration: 2,
ease: ['easeInOut', 'easeInOut'],
times: [0, 0.5, 1],
repeat: Infinity,
}}
/>
タイムラインコーホートの例
コードベースが motion.dev を使用していると仮定します。
モーションコンテキストから:
{
"nodes": [
{
"nodeId": "1111:22",
"codeSnippets": {
"motionDot": "<motion.div animate={{ x: [0, 100, 0] }} transition={{ duration: 2 }} />"
}
},
{
"nodeId": "3333:44",
"codeSnippets": {
"motionDot": "<motion.div animate={{ opacity: [1, 0, 1] }} transition={{ duration: 2 }} />"
}
}
],
"timelineCohorts": [
{
"rootNodeId": "1111:22",
"durationMs": 2000,
"loopMode": "loop",
"memberNodeIds": ["1111:22", "3333:44"]
}
]
}
node 1111:22 のアニメーションは duration: 2 で正しく設定されています。node 3333:44 のアニメーションも duration: 2 に設定します。
マージされたコード:
import { motion } from 'motion/react';
// コーホート1111:22(ループ)のメンバー
<motion.div
data-node-id="1111:22"
animate={{ x: [0, 100, 0] }}
transition={{ duration: 2, repeat: Infinity }}
/>
<motion.div
data-node-id="3333:44"
animate={{ opacity: [1, 0, 1] }}
transition={{ duration: 2, repeat: Infinity }} // コーホートのdurationに合わせる
/>
アンチパターン
1. デザインコンテキストからアニメーションを推測する
してはいけないこと: デザインコンテキストに motion.div が含まれているからといって、その値が有効であると想定する。
するべきこと: アニメーション値については常に get_motion_context を信頼する。デザインコンテキストの motion.* タグは単なる構造マーカーであり、値は含まれていません。
2. モーションのオーバーレイを無視する
してはいけないこと: アニメーション化されたノードがデザインコンテキストに存在しない場合、静かに削除する。
するべきこと: アニメーション化されたノードがデザインコンテキストコードに存在しない場合は、// TODO: コメントとサマリーの呼び出しを使用して、未サポートとしてマークする。
3. フォールバックNodeIdを正確なNodeIdより優先する
してはいけないこと: 常に fallbackNodeId を使用してコンポーネント本体をターゲットにし、インスタンスごとのモーションを無視する。
するべきこと: 正確な nodeId がデザインコンテキストに存在する場合は、それを優先する。fallbackNodeId は、正確な nodeId ルックアップが失敗した場合のフォールバックとしてのみ使用する。
4. display: contents ラッパーを無視する
してはいけないこと: アニメーション化されたグループを display: contents のままにして、変換を壊す。
するべきこと: グループがアニメーション化されている場合は、display: contents ラッパーを実際に配置された要素(absolute、relative など)に置き換え、変換を正しく伝達できるようにする。
5. イージング配列の長さを間違える
してはいけないこと: イージング配列の長さを、キーフレームの数(n)ではなく、セグメントの数(n-1)と一致させることを忘れる。
するべきこと: easing 配列が常にキーフレームの数より1つ少ない要素を持つようにする。
6. コーホート内のノードを個別のタイミングで実装する
してはいけないこと: コーホート内の各ノードに個別の duration を設定する。
するべきこと: コーホート内のすべてのノードを、コーホートの durationMs に設定された同じ duration で実装し、それらが同期して再生されるようにする。