use_figma — 모션을 위한 Figma 플러그인 API 스킬
use_figma MCP 도구를 위한 모션 컨텍스트입니다. figma-use는 기본적인 플러그인 API 규칙을 다룹니다. 두 파일을 함께 로드하세요.
모션 작업을 위해 use_figma를 호출할 때 항상 skillNames: "figma-use-motion" (쉼표로 구분하여 figma-use와 함께)을 전달하세요. 로깅 전용입니다.
런타임 게이팅
모션 API는 metronome 사용자 피처 플래그 뒤에 게이트되어 있습니다. 호출하는 사용자에게 이 플래그가 없으면, 이 스킬에서 참조하는 모든 모션 속성과 헬퍼가 "<name>"은(는) 지원되지 않는 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 | 애니메이션 이징 설정 시 | 키프레임 이징 객체, 커스텀 큐빅/스프링, HOLD, 애니메이션 스타일 내 이징 적용 |
애니메이션 확인
get_screenshot은 타임라인의 정지 상태만 보여줍니다. 모션을 확인하려면 export_video로 비디오를 내보내고 프레임을 샘플링하세요. 하지만 서버 측에서 렌더링되므로 느리고 비용이 많이 듭니다(~10초에서 수 분). 따라서 각 렌더링을 신중하게 만드세요.
렌더링 전에 계획하세요. 비용은 픽셀 × 프레임에 비례하므로, 필요한 최소 크기와 수로 유지하세요.
- 먼저 순간을 선택하세요. 부드러운 재생이 아닌 단계(예: 스태거 단계별, 또는 시작/중간/안정)별로 하나의 프레임이 필요합니다. 보통 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 사전 점검 목록에 추가로 다음을 확인하세요.
- 이징은
OUT_CUBIC과 같은 내부 신 그래프 이름이 아닌{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }공개 형태를 사용합니다. - 이즈인-아웃(in-out)은
EASE_IN_OUT이라는 잘못된 별칭을 절대 사용하지 않고 정확한 공개 열거형EASE_IN_AND_OUT(또는EASE_IN_AND_OUT_BACK)을 사용합니다. - 애니메이션 중인 노드가 최상위 프레임(페이지의 직계 자식)이 아닙니다. 대신 하위 요소에 애니메이션을 적용하세요.
- 타임라인 값은 공개 플러그인 API의 초 단위입니다.
setTimelineDuration으로 연장만 하고, 사용자가 요청하지 않는 한 단축하지 마세요. - 변환 키프레임 필드는 내부
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은 정지 상태만 보여줍니다.