모션 구현
개요
이 스킬은 Figma 애니메이션 및 전환을 실행 가능한 코드(motion.dev, CSS keyframes 또는 프레임워크 특화 라이브러리)로 변환하는 방법을 안내합니다.
Figma는 두 가지 도구를 통해 모션을 노출합니다:
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)로 렌더링할 수 있으며, 애니메이션 값은 인라인으로 포함하지 않습니다.
두 도구는 노드 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)
응답 형태(애니메이션 적용 노드당 하나의 항목):
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가 없다고 해서 애니메이션이 없다는 신호는 아닙니다. - 재귀 응답은 정확히 중복된 스니펫을 제거합니다. 스니펫이 동일한 모션을 가진 첫 번째 노드를 가리키는 주석으로 대체될 수 있습니다. 두 번째 애니메이션을 작성하는 대신 동일한 컴포넌트, 변형, 클래스 또는 상수를 재사용하십시오.
- MCP 서버는
clientFrameworks에서 CSS 대 motion.dev 스니펫을 추론합니다. 응답에 스니펫 형식이 하나만 포함된 경우, 다른 형식이 실패했다고 가정하지 말고 사용자 스택에 맞게 해당 형식을 조정하십시오.
3단계: 정적 및 모션 컨텍스트 병합
get_motion_context.nodes에서 시작하십시오. 정적 JSX의 보이는motion.*태그에서 시작하지 마십시오. 반환된 모든 노드는 애니메이션이 적용됩니다. 각 모션 노드를 정확한nodeId/data-node-id로 먼저get_design_context에 다시 연결하십시오. 정확히 일치하는 항목이 없는 경우에만fallbackNodeId/data-node-id를 시도하십시오. 두 ID가 모두 실패한 후에만 노드 이름/유형 및 스크린샷 위치로 폴백하십시오.- 정확한 ID 일치가
fallbackNodeId보다 우선합니다.fallbackNodeId는 D2R이 재사용 가능한 컴포넌트 내부에서 내보낼 수 있는 백업 컴포넌트 ID를 가리킵니다. 이는 해당 컴포넌트의 모든 인스턴스에서 공유됩니다. 정확한nodeId가 설계 컨텍스트에 존재하는 경우, 해당 위치에 모션을 적용하고 폴백은 무시하십시오. 이것은 루트 인스턴스 애니메이션에 중요합니다. 한 인스턴스는 동일한 컴포넌트의 다른 인스턴스와 다르게 회전하거나 이동할 수 있으며, 해당 모션을 공유 컴포넌트 본문에 적용하면 모든 인스턴스가 잘못 애니메이션됩니다. - 각 모션 노드를
data-node-id로 키가 지정된 일치하는 설계 컨텍스트 구조에 적용하십시오. 일치하는data-node-id는 구조적 앵커이며, 항상 모션을 수신하는 최종 DOM 요소는 아닙니다. 스니펫 모양과 배치 마커를 사용하여 모션이 정확한 요소, 래퍼, 내부 요소 또는 인라인 SVG 경로에 적용되어야 하는지 결정하십시오.get_design_context는 이미 값이 제거된motion.{tag}를 내보내거나, 일반 구조적 요소(div,p,span, 컴포넌트 루트 등)를 내보낼 수 있습니다. 요소가 일반 요소이고 스니펫이 요소 자체를 대상으로 하는 경우, 노드의 텍스트, 자식, 클래스/스타일, 속성 및data-node-id를 유지하면서 적절한motion.{tag}로 변환하거나 모션 래퍼를 추가하십시오. 이 병합 단계의 예를 보려면 references/examples-and-anti-examples.md를 로드하십시오. - 컴포넌트화된 자식 모션은 일반적으로 폴백으로 일치합니다. 설계 컨텍스트가 Figma 인스턴스를 재사용 가능한 React 컴포넌트로 추출할 때, 해당 컴포넌트 본문 내의 자식은 종종 백업 컴포넌트 ID(
4002:3957)를 가지는 반면, 모션 컨텍스트는 라이브 인스턴스 ID(I4005:6111;30:8005)를 보고합니다. 이 경우fallbackNodeId를 사용하여 컴포넌트 본문data-node-id를 찾지만, 모션은 구현 중인 렌더링된 인스턴스로 범위를 지정하십시오. 여러 인스턴스가 있고 하나만 다른 루트 모션을 가지고 있는 경우, 정확한 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> 모션 미지원주석을 남기고 요약에서 언급하십시오.- 노드가 모션 컨텍스트에는 나타나지만 정적 JSX에는 없는 경우, 이를 나타내는 데 필요한 요소를 추가하십시오. 설계 컨텍스트 코드는 참조일 뿐 완전한 애니메이션 인벤토리가 아닙니다.
- 설계 및 모션 컨텍스트 간에 충돌이 있는 경우(타이밍/이징/애니메이션 값),
get_motion_context를 우선시하십시오. - 경로 수준 SVG 모션: SVG를 인라인으로 포함하고 실제
<path>에 애니메이션을 적용하십시오.get_motion_context가 벡터의 경로(PATH_TRIM,motion.path,stroke-dasharray)를 대상으로 하지만 설계 컨텍스트가 이를<img>로 렌더링하는 경우, SVG를 인라인으로 포함하고 스니펫을<path>에 적용하되 레이아웃 래퍼는 유지하십시오. 이 경우(motion.path,pathLength="1", 래퍼+경로 레이어링, CSS path-trim)에 대한 전체 방법을 보려면 references/svg-and-path-motion.md를 로드하십시오.
인터리브 변환 처리
정적 기본 변환과 애니메이션 변환을 둘 다 가진 노드는 중첩된 요소로 분할되어 두 변환이 충돌하지 않고 올바르게 합성됩니다. 즉, data-motion-wrapper-for="<nodeId>"(외부 래퍼)를 전달하는 ID 없는 motion.div가 정적 변환 div(예: rotate-45 + hypot() 크기 조정 — 또는 래퍼 자체가 data-motion-transform-template="<css>"를 전달)를 래핑하고, 이는 다시 내부 노드(data-node-id)를 래핑합니다. 래퍼 > 정적-변환 div > 내부 중첩을 유지하십시오. 이를 축소하면 크기 조정 및 기본 변환이 깨집니다.
- 트랙을
data-motion-keys로 배치하십시오. 래퍼의data-motion-keys(변환 트랙 —x/y/rotate/scaleX/scaleY/skewX)는 외부 래퍼에 적용되고, 내부 요소의data-motion-keys는 내부 요소에 적용됩니다. data-motion-transform-template을 다시 적용하십시오. 래퍼가 하나를 전달하는 경우,transformTemplate={(_, generated) => "<css> " + generated}를 설정하여 애니메이션 변환이 해당 정적 레이아웃 변환 위에 합성되도록 하십시오.- 정적 베이스로 애니메이션 변환을 오프셋하십시오(이중 회전 방지).
get_motion_context는 노드의 절대 변환을 제공하며, 이는 해당 div가 적용하는 정적 베이스를 이미 포함합니다.rotate-45베이스 위의[45, 125, 125]회전 스니펫은 래퍼가 오프셋[0, 80, 80](= 절대 − 45)을 애니메이션한다는 것을 의미하며, 절대값이 아닙니다. 그렇지 않으면 45°가 두 번 적용되어 요소가 정지 상태에서 90°에 위치하게 됩니다. 정적 베이스가 없는 트랙(예: 0에서 시작하는x/y)은 변경되지 않고 통과됩니다. 인터리브 변환 예제를 참조하십시오. - 레이아웃 변환을 모션 변환과 분리하십시오.
rotate,scale또는skew를 애니메이션하는 모든motion.*요소에 대해, 또한 센터링/위치 지정을 위해-translate-x-1/2또는-translate-y-1/2와 같은 Tailwind 레이아웃 변환에 의존하지 않는지 확인하십시오. 이러한 유틸리티는 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 keyframes가 있습니까? 바닐라/비-React 대상, 또는 코드베이스에 React 모션 라이브러리가 없는 경우 사용하십시오.
- 스니펫이 없습니까?
keyframeBindings또는motionSummary를 폴백 데이터로 사용하여 동등한 motion.dev 호출 또는 CSS keyframes를 구성하십시오. 일반적으로 스니펫이 존재하므로, 두 스니펫 형식이 모두 확실히 누락된 경우에만 이 작업을 수행하십시오.
5단계: 검증
- 새 모션 가져오기/컨벤션을 추가하기 전에 컴포넌트의 기존 모션 가져오기/컨벤션을 읽으십시오. 사용자가 이미 Framer Motion / React Spring / anime.js를 사용하는 경우, motion.dev를 강제하기보다는 적응하십시오.
- 여러 노드에서 변경 사항을 일괄 적용하기 전에 하나의 애니메이션이 처음부터 끝까지 실행되는지 스팟 체크하십시오(리로드, 관찰, 반복).
- 이 경우를 구현하기 전에 references/gotchas.md를 로드하십시오.
6단계: (선택 사항) 타임라인 조정
get_motion_context가 timelineCohorts를 반환하는 경우, 각 코호트 내의 모든 노드에 대해 whileInView={{ ... }} + 동일한 transition 설정을 사용하여 함께 애니메이션되도록 하십시오. 코호트를 개별 initial/animate 또는 viewport 자식에 의존하지 마십시오. 지연/재생 구성을 일치시키는 대신 코호트 단위로 처리하십시오.
추가 고려 사항
- Turborepo / 모노레포: 요약에 어떤 패키지가 수정되었는지 기록하십시오.
get_design_context코드를 그대로 복사하지 마십시오. 설계 컨텍스트는 구조적 참조입니다. 모든 요소를 있는 그대로 복사하지 말고 애니메이션 노드에 필요한 구조만 가져와야 합니다.- 설계 컨텍스트의 일부 요소는
@apply, 직접 스타일 또는 구성 사용자 정의를 통해 Tailwind가 아닌 CSS 클래스를 사용할 수 있습니다. 필요한 경우 인라인 스타일을 선호하십시오.
참조
- examples-and-anti-examples.md — 일반적인 병합 패턴
- framework-recommendations.md — 라이브러리별
- svg-and-path-motion.md — 벡터 애니메이션 방법
- gotchas.md — 자주 놓치는 사항
- overview-of-motion.md — Figma 모션 데이터의 개념적 개요
- recommended-prompts.md — 사용자에게 보낼 수 있는 프롬프트 예시