플러그인 설치: 설정 또는 업데이트 명령을 실행하기 전에, 이 스킬이 HyperFrames 플러그인 내부에 있을 경우 플러그인 실행 규칙을 따르세요. 독립 실행형 설치는 아래 업데이트 지침을 유지합니다.
먼저, 이 스킬을 최신 상태로 유지하세요 — 실행 전 사용자에게 확인:
npx hyperframes skills update motion-graphics. 모든 것이 최신 상태이면 빠른 no-op; 그렇지 않으면 이 스킬과 이 스킬이 의존하는 핵심 도메인 스킬을 새로 고친 후 사용합니다.
figma 소스: 로고/에셋/애니메이션을 빌드할 figma.com URL이 있는 경우, 먼저
/figma를 실행하세요 — 에셋 내보내기, 브랜드 토큰, 그래픽이 Figma Motion 가져오기인 경우 Motion→GSAP 변환 — 그런 다음 해당 출력을 기반으로 빌드합니다. 원시 MCP 도구를 통해 Figma를 직접 구동하지 마세요: SVG 정리,.media/manifest.jsonl출처, 브랜드 토큰var()바인딩을 건너뛰므로, 나중에 브랜드 변경 시 전체 재가져오기 없이는 전파될 수 없습니다.
motion-graphics — 디스패치 진입점
정문은
/hyperframes입니다. 이 스킬은 짧고, 디자인 중심이며, 내레이션이 없는 모션 그래픽을 만듭니다 (모션이 메시지이며, 약 10초 미만, 음성 해설 없음). 더 길거나, 내레이션이 있거나, 여러 장면인 경우 — 또는 불확실한 경우 → 먼저/hyperframes를 읽으세요: 의도 레이어가 모든 경로 결정을 소유합니다.
이 워크플로우는 설계상 자율적입니다 — 최대 하나의 명확화 질문(agents/director.md) 후 중간 검토 없이 검증을 통해 빌드합니다. 의도 레이어(/hyperframes → references/intent-interview.md)는 실행 형태 질문 없이 여기로 직접 라우팅합니다. 이렇게 짧은 조각에는 스토리보드와 동반 세션이 거의 도움이 되지 않습니다. 렌더링은 여전히 사용자 제어: 검사 및 증명 스냅샷이 통과한 후, ../hyperframes/references/brief-contract.md의 표준 "미리보기 먼저, 아니면 렌더링?" 질문을 합니다. BRIEF.md가 존재하면, 디렉터 질문 전에 그것을 읽습니다.
짧은 디자인 중심 모션 그래픽. 자산 우선: 샷을 디자인하기 전에 자산 전략을 결정하고 실제 재료를 소싱한 다음, 가지고 있는 것을 중심으로 샷을 디자인하고, 카탈로그 기능을 재사용하여 구성합니다. 모든 아티팩트는 PROJECT_DIR = videos/<project-name>/ (0단계에서 생성) 아래에 배치됩니다. 아래 모든 경로는 이에 상대적입니다.
| 단계 | 실행 | 주요 아티팩트 | 상세 흐름 |
|---|---|---|---|
| 초기화 | Bash | hyperframes.json | 0단계 |
| 계획 | 서브에이전트 — 검색 결정? + 분류 + 자산 전략 | shot-plan.json (초안: 카테고리, asset_needs 쿼리, 브리핑) | agents/director.md (1부) |
| 소싱 ◇ | Bash — 미디어 사용 해결 (asset_needs가 비어 있으면 건너뜀) | assets/ + assets/index.md | phases/source/guide.md |
| 디자인 | 서브에이전트 — 해결된 자산 중심 샷 디자인 | shot-plan.json (최종: 블록 + 레이아웃 + 모션 + 위치) | agents/director.md (2부) |
| 빌드 | 서브에이전트 — 재사용 우선 구성 | compositions/index.html | agents/builder.md |
| 검증 | Bash — lint, check, 증명 스냅샷; 실패 시 수리 | snapshots/contact-sheet.jpg | 5단계 |
| 승인 | 미리보기 또는 렌더링 질문; 답변 대기 | 명시적 렌더링 승인 | 6단계 |
| 렌더링 | Bash — hyperframes render (MP4, 또는 오버레이용 --format webm/mov) | renders/video.mp4 또는 투명 오버레이 | 6단계 |
◇ 소싱은 선택한 카테고리가 자산을 선언할 때만 실행됩니다. 순수 코드/텍스트 카테고리(예: kinetic-type, 대부분 charts/stat)는 asset_needs: []이고 계획에서 디자인으로 바로 건너뜁니다.
카테고리 — 검색 결정에 따른 분할
계획의 첫 번째 결정은: 검색이 필요한가? 입니다. 이 분기는 카테고리를 두 그룹으로 나눕니다. 그런 다음 특정 카테고리가 선택됩니다 — 검색 주도형의 경우 검색이 반환하는 콘텐츠 유형별로. 각 카테고리는 하나의 categories/<id>/module.md (계획 + 빌드 규칙)입니다. 공유 모션 어휘는 references/motion-vocabulary.md (→ hyperframes-animation 규칙/청사진 + 레지스트리 블록)에 있습니다.
형식 카테고리 — 검색 없음; 사용자가 콘텐츠를 제공:
| 카테고리 | 의도 | 의존 |
|---|---|---|
kinetic-type | 강력한 한 줄 / 인용구 / 제목, 모션 우선 텍스트 | caption-* 블록 + 애니메이션 규칙 |
stat | 단일 히어로 숫자 / 카운트업 + 링 | apple-money-count / rules/{counting-dynamic-scale, stat-bars-and-fills} |
charts | 데이터에서 막대 / 선 / 원형 / 레이스 / % 차트 | data-chart 블록 |
logo-reveal | 로고 스팅 / 브랜드 잠금 (사용자 로고) | logo-outro / rules/svg-path-draw |
lower-thirds | 이름 / 제목 바, 콜아웃, SNS 오버레이 | caption-* + 레지스트리 오버레이 블록 |
maps | 지리적 모션 — 지역 강조, 장소 연결, 위치로 확대/축소 (벡터 레인 또는 베이크드 베이스맵 레인) | us-map / world-map 패밀리 + bake-basemap.mjs |
검색 주도형 카테고리 — 먼저 검색한 다음 콘텐츠 유형별로 애니메이션 (RWA 경로):
| 반환된 콘텐츠 | 카테고리 | 애니메이션 |
|---|---|---|
| 웹페이지 / 링크 | webpage | 웹페이지 / UI 애니메이션 (스크롤, 나타내기, 커서, 콜아웃) |
| 뉴스 기사 | news | 헤드라인 나타내기 + 소스 카드 + 주요 사실 콜아웃 |
| 트윗 | tweet | 애니메이션 트윗 카드 |
| 이미지 / 엔터티 | asset-fusion | 자산의 지오메트리가 차트가 됩니다 (RWA 다이제틱 퓨전) |
빌드 순서: 한 번에 하나씩, 커버리지 우선 (대략적으로 괜찮음). kinetic-type은 프로토타입에서 이식됨; 나머지는 따름.
전제 조건
macOS Apple Silicon 또는 Linux x64. 시스템 도구: brew install node ffmpeg. npx hyperframes doctor 한 번. macOS GPU 렌더링: export PRODUCER_BROWSER_GPU_MODE=hardware.
선택적 키 (설정되지 않은 경우 로컬 폴백) — 미디어 사용을 통해 자산을 소싱/생성하는 카테고리에만 필요:
| 키 | 용도 | 폴백 |
|---|---|---|
GEMINI_API_KEY / GOOGLE_API_KEY | 이미지 생성 (미디어 사용 해결) | 생성 건너뛰기 / 검색 전용 |
| (asset_scout / 검색 공급자) | webpage/news/tweet + asset-fusion 실제 자산 검색 | 카테고리가 자산 없음으로 저하됨 |
흐름
0단계 — 초기화
cwd는 에이전트 작업 공간 루트입니다. PROJECT_DIR = videos/<project-name>/ 아래에 모든 아티팩트를 작성합니다. <project-name>: 사용자가 제공한 디렉토리를 사용하고, 그렇지 않으면 의도에서 짧은 케밥-케이스 이름을 사용합니다 (<subject>-motion). 작업 공간 기본 이름이나 타임스탬프는 사용하지 않습니다.
$PROJECT_DIR/hyperframes.json이 없을 때만:
PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=motion-graphics
init는 설치된 스킬을 GitHub의 최신 버전과 비교하고 오래된 경우 글로벌 세트를 업데이트합니다.
제약 조건: 작업 공간 루트에서 hyperframes init를 절대 실행하지 마십시오. PROJECT_DIR 안에 다른 hyperframes/를 중첩하지 마십시오. 모든 Bash 명령 (마스터 + 서브에이전트)은 (cd "$PROJECT_DIR" && ...) 서브쉘입니다 — 절대 cd 단독으로 사용하지 마십시오.
1단계 — 계획 (서브에이전트: Director 1부)
하나의 서브에이전트를 디스패치합니다. 프롬프트 = 전체 agents/director.md + ## Dispatch context (SKILL_DIR / PROJECT_DIR / 사용자 요청 / Schema: <SKILL_DIR>/references/shot-plan-ir.md). 다음을 수행해야 합니다:
- 결정: 검색이 필요한가? (첫 번째 분기)
- 아니요 → 형식 카테고리 선택 (kinetic-type / stat / charts / logo-reveal / lower-thirds); 콘텐츠는 사용자 제공;
asset_needs: []. - 예 → 검색 계획을
asset_needs[]로 내보냄 (뉴스 / 웹 / 트윗 / 이미지; 양극 쿼리). 특정 검색 주도형 카테고리 (webpage / news / tweet / asset-fusion)는 2단계에서 반환된 콘텐츠 유형으로 확인되고 3단계에서 최종 확정됩니다.
- 아니요 → 형식 카테고리 선택 (kinetic-type / stat / charts / logo-reveal / lower-thirds); 콘텐츠는 사용자 제공;
- 초안
shot-plan.json작성 (엔벨로프 + 선택한 형식 카테고리 또는 검색 의도 +asset_needs+ 한 문단 분량의 샷 브리핑). 스키마:references/shot-plan-ir.md.
검증: [ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing.
2단계 — 소싱 ◇ (Bash: media-use, 조건부)
shot-plan.json.asset_needs가 비어 있지 않으면 자산 해결 (검색 / 생성 / 가져오기 → 고정된 프로젝트-로컬 경로 + 원장). phases/source/guide.md 참조 (media-use resolve 래핑; 검색 주도형 카테고리는 뉴스/웹/트윗/이미지 검색 사용). asset_needs가 비어 있으면 3단계로 건너뜁니다.
# 설명용 — phases/source/guide.md 참조
(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)
정상 저하: 검색/공급자를 사용할 수 없으면 카테고리는 자산 없음으로 대체됩니다 (context.log에 기록).
3단계 — 디자인 (서브에이전트: Director 2부)
서브에이전트를 디스패치합니다 (프롬프트 = agents/director.md 2부 + 해결된 assets/index.md (2단계가 실행된 경우) + catalog-map.md를 포함한 디스패치 컨텍스트). 사용 가능한 자산을 중심으로 샷을 디자인합니다: 카탈로그 블록 + hyperframes-animation 규칙/청사진, 레이아웃, 모션, 비트, (asset-fusion의 경우) element_positions + 스포이드 팔레트를 선택합니다. shot-plan.json을 최종 확정합니다 (content.block + content.customize + 카테고리별 콘텐츠).
4단계 — 빌드 (서브에이전트: Builder, 재사용 우선)
서브에이전트를 디스패치합니다. 프롬프트 = 전체 agents/builder.md + 디스패치 컨텍스트 (shot-plan.json, catalog-map.md, 카테고리의 module.md, references/motion-vocabulary.md, references/builder-contract.md). 재사용 우선: npx hyperframes add <block> + 제자리에서 사용자 정의; 격차 + 자산 퓨전 어포던스만 수동 작성. HF 계약을 준수하는 compositions/index.html 출력 (일시 중지된 GSAP 타임라인 window.__timelines, class="clip" + 안정적인 ID, tl.seek(0), 결정론적).
5단계 — 검증 (Bash → 실패 시 수리 서브에이전트)
(cd "$PROJECT_DIR" && npx hyperframes lint .)
(cd "$PROJECT_DIR" && npx hyperframes check .)
(cd "$PROJECT_DIR" && npx hyperframes snapshot --at <proof-times>)
시작 상태, 시그니처 동작 및 최종 홀드를 표시하는 증명 시간을 선택합니다. 계속하기 전에 생성된 연락처 또는 스냅샷 시트를 검사합니다. lint, check, 또는 스냅샷 실패 시, 수리 서브에이전트(agents/finalize.md)를 한 번의 제자리 수정 패스로 디스패치한 다음 실패한 게이트를 다시 실행합니다. 결함을 숨기기 위해 고정된 지속 시간을 변경하지 마십시오.
6단계 — 승인 및 렌더링 (Bash)
한 가지 질문을 합니다: "미리보기 먼저, 아니면 렌더링?" 사용자가 미리보기를 선택하면 Studio를 열고 수정 후 동일한 승인 게이트로 돌아갑니다:
(cd "$PROJECT_DIR" && npx hyperframes preview --background)
명시적인 렌더링 답변 후에만 렌더링합니다:
(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q high -o ./renders/video.mp4)
# 투명 오버레이 변형: --format webm (또는 mov)
출력이 존재하고, 비어 있지 않으며, 의도된 지속 시간인지 확인합니다. 최종 핸드오프는 아티팩트 이름, 실제 지속 시간, 구성 또는 프레임 ID, 증명 시간 및 검사된 연락처 또는 스냅샷 시트를 지정합니다. 플래그는 /hyperframes-cli → references/preview-render.md에 있습니다.
재개 테이블
| 상태 | 계속 위치 |
|---|---|
shot-plan.json 없음 | 1단계 (계획) |
shot-plan.json에 asset_needs가 있지만 assets/ 없음 | 2단계 (소싱) |
shot-plan.json 최종, compositions/index.html 없음 | 3/4단계 (디자인+빌드) |
compositions/index.html 존재, 증명 스냅샷 없음 | 5단계 (검증) |
| 검사 및 증명 스냅샷 통과, 승인된 렌더링 없음 | 6단계 (승인) |
| 승인된 렌더링 존재 | 출력 확인 후 보고 |
디자인 노트 (유지 관리자 — 실행 시 이 내용을 읽지 않음)
- 자산 우선 근거: 소싱은 프론트-로드되고 샷 디자인에 정보를 제공합니다 (RWA 흐름: 분석 → 검색 → 검토 → 구성).
- 일반 동작: hyperframes-animation의
rules/는 가능한 모든 모션을 다루려고 하지 않습니다. 대신, 자주 사용되는 패턴 (카운팅, SVG 경로 그리기, 스크롤 마스크)에 대한 핸드-롤링 가드레일을 제공하고 유연한motion-vocabulary.md사양을 통해 나머지를 오픈 엔드로 둡니다. - GSAP 특이성: 모든 애니메이션은
gsap.to()(요소 속성)을 사용합니다;gsap.from()은 초기 상태가 암시적이므로 선호되지 않습니다. 타임라인은window.__timelines배열에 등록되어야 합니다. - 에셋 퓨전 분류:
asset-fusion카테고리는media-use resolve가 단일 이미지 엔터티를 반환할 때 선택됩니다. 에이전트는 지오메트리 스와핑을 위해elements/asset-fusion/affordance.mjs스크립트를 참조해야 합니다. - 렌더링: 출력은 항상
renders/디렉토리에 저장되며, 투명 오버레이에는 WebM이 선호됩니다. Mov는 QuickTime에 투명도를 유지하지만 파일 크기가 더 큽니다. - 에러 처리: 모든 서브에이전트 호출은 출력 아티팩트 확인 후 검증해야 합니다. 실패 시 재시도 로직은 지수 백오프를 사용하여 빌드 루프를 방지해야 합니다.
- 성능:
npx hyperframes snapshot명령은 증명 시간에만 프레임을 캡처합니다. 전체 비디오를 스냅샷하지 마십시오. 증명 시간은 일반적으로 시작, 중간 및 종료 상태를 포함합니다.