use_figma — Figma 플러그인 API 모션 스킬은(는) 무엇을 하나요?
use_figma MCP 도구를 위한 모션 컨텍스트입니다. figma-use가 기본 플러그인 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)— 전체 객체를 다시 쓰지 않고 하나의 수동 키프레임 트랙을 추가, 교체 또는 제거합니다.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 | 애니메이션 이징 설정 | 키프레임 이징 객체, 사용자 정의 cubic/spring, HOLD, 애니메이션 스타일 내 이징 적용 |
애니메이션 확인
get_screenshot은 타임라인의 정지 상태만 보여주며, 모션은 보여주지 않습니다. 모션을 확인하려면 export_video로 프레임을 샘플링하세요. 단, 서버 측에서 렌더링되므로 느리고 비용이 많이 듭니다 (~10초에서 수 분). 따라서 각 렌더링을 효율적으로 사용하세요.
렌더링 전에 계획하세요 — 비용은 픽셀 × 프레임에 비례하므로, 필요한 프레임보다 크게 만들지 마세요:
- 먼저 순간을 선택하세요. 부드러운 재생이 아닌 단계당 하나의 프레임이 필요합니다 (예: stagger 단계별, 또는 시작/중간/안정화). 보통 4–6개입니다. 이 개수가 fps를 결정합니다.
- 읽을 수 있는 크기로 조정하세요. 작게 시작하세요 —
constraint: { type: 'WIDTH', value: 320 },quality: "low"— 하지만 텍스트와 작은 요소는 흐려지므로 세부 판단이 필요하면WIDTH를 (768+) 높이세요.constraint를 생략하면 전체 크기(1x; 서버는 10x / 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와 같은 프레임 추출기가 없으면 내보내기를 건너뛰고 키프레임에 대해 추론하세요.
올바를 때까지 반복하세요. 내보내기는 진단 도구이지 승인이 아닙니다: 프레임이 잘못된 경우 (잘못된 순서, 타이밍 오류, 요소 누락, 컴포지트를 가리는 마스크) 키프레임/스타일을 수정하고 다시 내보내세요. 모든 프레임을 읽고, 다시 렌더링하기 전에 모든 수정을 한 번에 모아서 처리하세요. 각 렌더링에는 실제 오버헤드가 따르므로, 작은 변경마다 다시 내보내기보다 각 렌더링을 효율적으로 만드세요.
사소하거나 자명한 변경의 경우 내보내기를 완전히 건너뛰세요.
사전 점검 목록
figma-use 사전 점검 목록에 추가로 다음을 확인하세요:
- 이징은 공개
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }형태를 사용합니다.OUT_CUBIC같은 내부 scenegraph 이름을 사용하지 마세요. - Ease-in-out은 정확한 공개 열거형
EASE_IN_AND_OUT(또는EASE_IN_AND_OUT_BACK)를 사용합니다. 유효하지 않은 별칭EASE_IN_OUT을 절대 사용하지 마세요. - 애니메이션 대상 노드가 최상위 프레임(페이지의 직접 자식)이 아닙니다. 대신 하위 노드를 애니메이션 처리하세요.
- 타임라인 값은 공개 Plugin API에서 초 단위입니다.
setTimelineDuration으로 연장하고, 사용자가 요청하지 않았다면 절대 단축하지 마세요. - 변환 키프레임 필드는 공개 이름 (
TRANSLATION_X,TRANSLATION_Y,ROTATION,SCALE_X,SCALE_Y,SCALE_XY)을 사용합니다. 내부MOTION_*scenegraph 이름을 사용하지 마세요. - 수동 키프레임 필드는 motion-patterns.md의 공개 허용 목록에서 가져옵니다. 생성된/내부 scenegraph 필드는 의도적으로 오류를 발생시킵니다.
- 변경된 노드 ID가 반환됩니다 (
figma-use규칙 15 참조). - 모션 정확성이 자명하지 않고 프레임 추출기(
ffmpeg)를 사용할 수 있는 경우,export_video+ 프레임 샘플링을 통해 확인하세요. 작게 렌더링하고, 낮은fps로 설정하고, 올바를 때까지 반복하세요 (위의 '애니메이션 확인' 섹션 참조).get_screenshot은 정지 상태만 보여줍니다.