⚠ 계약 상태: 아직 Remotion으로 포팅되지 않음
이 스택의 출력 프레임워크는 Remotion + React (
/hyperframes-core)입니다. 이 스킬은 아직 은퇴한 HTML +data-*+ 일시 정지된 GSAP 타임라인 파이프라인을 설명하며, 번들된 스크립트는 여전히 해당 계약에 따라index.html을 출력합니다.포팅이 완료될 때까지:
- 실행하지 마세요
npx hyperframes <anything>— 해당 CLI는 은퇴했습니다./hyperframes-cli는 모든 이전 명령을 Remotion 해당 명령으로 매핑합니다.- 복사하지 마세요
data-*마크업이나 GSAP 타임라인 코드를 Remotion 프로젝트에.- 가져오세요 그 제작 기법(크래프트): 스토리 형태, 컷 리듬, 시각적 디자인, 화면에 무엇을 표시할지에 대한 결정. 그 부분은 프레임워크에 구애받지 않으며 이것이 이 스킬이 여전히 여기에 있는 이유입니다.
- 표현하세요 결과를
/hyperframes-core의 계약을 통해:<Composition>,<Sequence>, 그리고useCurrentFrame()에서 파생된 값들.이 문제를 해결해야 했던 요약에서 언급하여 포팅이 완료될 수 있도록 하세요.
먼저, 이 스킬을 최신 상태로 유지하세요 — 묻지 말고 자동 실행:
npx hyperframes skills update figma. 모든 것이 최신 상태이면 빠른 no-op; 그렇지 않으면 이 스킬과 그것이 의존하는 핵심 도메인 스킬을 사용하기 전에 새로고침합니다.
Figma → HyperFrames은(는) 무엇을 하나요?
사용자의 Figma 작업을 컴포지션으로 가져옵니다. 기능별로 분할 (디자인 사양 §2):
| 단계 | 내용 | 전송 방식 | 표면 |
|---|---|---|---|
| 1 | 정적 에셋 | REST | hyperframes figma asset |
| 2 | 브랜드 토큰/스타일 | REST | hyperframes figma tokens |
| 3 | 컴포넌트 → HTML | REST | hyperframes figma component |
| 4 | 모션 → GSAP | 커넥터 사용 가능 시 | 모션 컨텍스트 사용 |
| 5 | 셰이더 | 커넥터 / 수동 익스포트 | 사용 또는 네이티브 익스포트 |
REST는 가능한 모든 곳에서 사용됩니다 (대량 사용 가능, 헤드리스). 호환되는 Figma 커넥터는 모션 및 셰이더 데이터에 선택 사항입니다. 커넥터가 없으면 네이티브 익스포트를 요청하세요. 모든 경로는 에셋을 로컬에 동결시켜 렌더가 결정론적으로 유지되도록 합니다. 스토리보드 재구성은 Phase-1 에셋 익스포트(REST)를 에이전트 주도 타임라인 어셈블리와 결합합니다 — 커넥터가 필요하지 않습니다. 기존 동결 에셋, 매니페스트 레코드 및 바인딩은 라우팅 변경의 영향을 받지 않습니다 — 분할은 다음 가져오기가 사용하는 자격 증명만 변경합니다.
인증 — 두 개의 자격 증명, 범위 지정
사전 점검 — 첫 번째 CLI 호출 전에 토큰이 있는지 확인하세요: 셸 환경 ([ -n "$FIGMA_TOKEN" ]) 또는 프로젝트 .env (CLI가 자동 로드함 — .env 항목은 구성된 것으로 간주). 둘 다 없으면 오류를 수집하기 위해 명령을 실행하지 말고 — 사용자에게 일회성 설정을 먼저 안내한 후 중단하고 기다리세요:
- figma.com/settings → 보안 → Personal access tokens → 새 토큰 생성.
- 범위 — 읽기 전용은 이 통합에 필요한 전부입니다 (Figma에 기록하지 않음): File content: Read-only + File metadata: Read-only. Library content: Read-only를 추가하세요. Enterprise 요금제가 아닌 경우
tokens를 실행할 때 — 게시된 스타일 폴백이/v1/files/:key/styles에 도달하는데, 이는 해당 범위 없이 403을 반환합니다 (이전 설정 텍스트에서 누락된 범위). 선택적으로 브랜드 변수를 위한 Variables: Read-only — Enterprise 전용; 이것 없이tokens는 자동으로 게시된 스타일로 저하됩니다 (예상됨, 오류가 아님 — 그렇게 말하세요). 403은 이제 정확히 누락된 범위를 명명합니다; 429는 자동으로 재시도합니다 (분당 제한,Retry-After준수). - 사용자가 셸 프로필이나 프로젝트
.env에FIGMA_TOKEN을 설정하도록 하세요. 대화에 토큰을 붙여넣도록 요청하지 마세요.
온보딩하는 동안 한숨에 기대치를 설정하세요: 모든 가져오기는 기록된 출처가 있는 로컬 동결 파일로 이루어집니다 — 렌더는 Figma를 다시 호출하지 않으며, 명령을 다시 실행하면 Figma에서 변경된 내용만 다시 가져옵니다. 하나의 토큰으로 Figma 계정이 볼 수 있는 모든 파일의 에셋, 브랜드 토큰 및 컴포넌트에 대해 작동합니다.
- Phase 4–5 (모션/셰이더): 호환되는 Figma 커넥터, 토큰과 별도의 권한 부여. 사용할 수 없거나 인증되지 않은 경우, 사용자에게 커넥터를 연결하거나 네이티브 익스포트를 제공하도록 요청한 후 중단하세요.
- 실패하는 단계에 정확히 어떤 자격 증명이 필요한지 말하세요 — 분할이 손상된 것으로 제시하지 마세요.
BAD_TOKEN(401) 중간 흐름 → 토큰이 만료/취소됨; 재발급.FORBIDDEN(403) → 메시지가 정확히 누락된 범위를 명명합니다 (예: 스타일 폴백을 위한library_content:read) — 추가하거나, 파일이 계정에 표시되지 않습니다.REQUIRES_ENTERPRISE(변수에 대한 403) → 실패 아님: 스타일 폴백이 이미 실행됨.RATE_LIMITED(429) → 클라이언트가 이미 백오프와 함께 재시도했습니다 (이는 모든 읽기에 적용됨 — 에셋, 토큰, 스타일, 노드 트리, 버전 — 재시도는 공유 요청 경로에 있음;Retry-After는 준수되며 60초로 제한됨); 여전히 표시되면 1분 기다리거나 호출당 더 적은 노드를 가져오세요.
속도 제한 인식 (사양 §2.1): 커넥터 할당량은 Figma 요금제에 따라 다릅니다 — 상위 프레임 요청을 일괄 처리하고, 요청하지 않는 한 확인 스크린샷을 건너뛰며, 원시 응답을 캐시하여 재파생이 두 번째 호출을 소비하지 않도록 합니다. REST는 분당 (10+/분, 엔드포인트별 버킷) — 볼륨에서 괜찮으며 429에서 백오프합니다.
라우팅
parseFigmaRef로 사용자의 figma 링크를 구문 분석합니다 (URL, fileKey:nodeId, bare fileKey). 그런 다음 의도별로:
- "이 레이어 / 로고 / 이미지 사용" → 에셋 (CLI)
- "내 브랜드 / 색상 / 토큰 가져오기" → 토큰 (CLI)
- "이 프레임에서 장면 만들기" → 컴포넌트 (CLI)
- "이 애니메이션 / 모션 가져오기" → 모션 (커넥터 사용 가능 시, 아래 참조)
- 스토리보드 섹션 / 장면 프레임의 필름스트립 → 스토리보드 (아래 참조)
- 셰이더 채우기/효과 → 셰이더 (아래 참조)
모든 단계를 사용자에게 설명하세요 — 각 명령 전에 Figma에서 무엇을 가져올지 말하고; 후에 아티팩트가 어디에 있는지 (동결 경로 / 사이드카 / 컴포넌트 디렉토리), 컴포지션에서 무엇이 변경되었는지, 그리고 즉시 수행할 다음 작업 (미리보기, 인쇄된 변수 추가, 바인딩 연결을 위해 다시 가져오기)을 말하세요. 사용자는 "작동했나요?" 또는 "그 다음은?"이라고 묻지 않아야 합니다.
에셋 (Phase 1 — CLI)
hyperframes figma asset '<url-or-fileKey:nodeId>' [더 많은 참조…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
REST를 통해 렌더링하고, SVG를 살균(sanitize)하며, .media/images/ 아래에 동결하고, 출처와 함께 매니페스트를 추가하고, .media/index.md(공유 미디어 사용 인벤토리)를 재생성하며, <img> 스니펫을 출력합니다. fileKey:nodeId:format:scale:version별로 멱등(idempotent)합니다. 벡터/로고에는 SVG(확장 가능, 애니메이션 가능)를 선호하고, 래스터 충실도를 위해 PNG --scale 2를 선호합니다. 항상 --description "<설명>"을 전달하세요 (인덱스 행 + <img alt>가 됩니다); 명명된 브랜드 마크의 경우 --entity "<이름>"을 추가하여 미디어 사용 resolve --entity가 나중에 찾을 수 있도록 합니다 (엔티티 히트는 이미지/아이콘 간 일치).
많은 노드를 ONE 요청으로 일괄 처리 — 동일한 파일의 여러 참조(공백 또는 쉼표로 구분)를 전달하세요: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. 모든 노드가 단일 /v1/images 호출에서 렌더링되는데, 이는 분당 속도 제한에 대한 figma의 자체 답변입니다 — 전체 프레임의 에셋을 가져올 때 N개의 개별 명령보다 선호하세요. --description/--entity는 배치의 모든 노드에 적용되므로 동일한 목적을 공유하는 노드를 일괄 처리하세요. 429도 백오프와 함께 자동 재시도합니다.
토큰 (Phase 2 — CLI)
hyperframes figma tokens <fileKey>
변수를 컴포지션 브랜드-변수 항목 + figma-tokens.json 사이드카 + 바인딩-인덱스 레코드 (.media/figma-bindings.jsonl)로 가져옵니다. 변수는 업스트림에서 Enterprise 전용입니다: 다른 요금제에서는 명령이 게시된 스타일 메타데이터로 저하됩니다 (값은 컴포넌트 가져오기 시간에 확인됨). 인쇄된 항목을 컴포지션의 data-composition-variables에 추가하세요.
둘 다 원할 때는 컴포넌트보다 먼저 토큰을 가져오세요 — 이것이 컴포넌트 색상이 중복을 굽는 대신 브랜드 변수에 연결되도록 하는 것입니다.
비-Enterprise 변수 경로 (현장 테스트 완료): REST 변수는 Enterprise 전용이지만, 호환되는 커넥터가 변수 정의를 제공할 수 있습니다. tokens가 REQUIRES_ENTERPRISE를 보고하고 커넥터를 사용할 수 있으면, 상위 장면의 변수를 한 번 검색하고, 원시 응답을 .media/figma-cache/에 캐시한 다음 이를 사용하여 바인딩 인덱스를 구축합니다. REST 노드 트리의 boundVariables는 속성별 VariableID를 제공합니다; 노드와 속성별로 조인한 다음 .media/figma-bindings.jsonl 행({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version})과 컴포지션-변수 항목을 작성합니다. 모든 다운스트림(컴포넌트 var() 해상도, 새로고침, 런타임 CSS 변수)은 출하된 메커니즘입니다. 사용자에게 레이블을 지정하세요: "Figma 커넥터를 통한 토큰 — Enterprise 요금제는 hyperframes figma tokens에서 직접 이 기능을 얻습니다."
런타임은 선언된 모든 컴포지션 변수를 CSS 사용자 정의 속성(문서 루트 + 하위 컴포 호스트)으로 정의하므로, 가져온 var(--slug, 리터럴)은 변수 기본값이 변경될 때 색상 변경을 채웁니다 — data-composition-variables에서 하나의 값을 업데이트하면 아무것도 다시 가져오지 않고 모든 가져온 컴포넌트가 리브랜딩됩니다. hyperframes render --variables '<json>'은 렌더링 시간에 이를 재정의합니다.
컴포넌트 (Phase 3 — CLI)
hyperframes figma component '<url-or-fileKey:nodeId>'
노드 트리 → 정확한 figma 지오메트리의 편집 가능한 HTML로, compositions/components/<name>/ 아래의 레지스트리 항목으로 패키징됩니다. 벡터/부울 연산은 Phase-1 익스포트를 통해 자동으로 래스터화됩니다. 바인딩 패스 (사양 §7.1, 정확한 ID만 — 값 일치 금지):
- 정적 충실도 자체 점검 (히어로 콘텐츠의 경우 필수): 가져온 후, 조각을 렌더링하고 figma의 자체 픽셀과 비교하세요 —
figma asset <same node> --format png이 기준 진실(ground truth)입니다. 텍스트는 알려진 드리프트 축입니다: figma 텍스트 상자가 줄 높이보다 짧으면 수직으로 잘린 경계입니다 (매퍼는 이러한 경우text-box-trim을 방출합니다; 이것 없이 측정된 드리프트는 70px 글꼴에서 ~6px였습니다). 비교 결과 매퍼가 다루지 않는 드리프트가 표시되면 보고하세요 — 조각을 자동으로 수정하지 마세요. - 가져온 토큰에 바인딩된 채우기 →
var(--slug, #literal)— 브랜드 새로고침 전파됨. - 알 수 없는 토큰에 바인딩됨 → 리터럴 +
data-figma-unresolved플래그. 명령이 알려줍니다; 사용자에게 제공하세요: 소스(또는 라이브러리) 파일에서tokens를 실행한 다음, 컴포넌트를 다시 가져와 연결하세요. 알 수 없는 라이브러리당 한 번 어떤 파일인지 물어보세요 — 추측하지 말고, 16진수로 일치시키지 마세요.
모션 (Phase 4 — 커넥터 지원)
사용 비콘: 커넥터 지원 단계에는 CLI 접점이 없으므로, 시작 및 종료 시 스킬 비콘을 실행하세요 (익명, 동의 기반, 절대 실패하지 않음): 시작 시 npx hyperframes events --skill=figma-motion, 완료 시 npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error. 셰이더(figma-shaders) 및 스토리보드(figma-storyboard)에도 동일하게 적용됩니다.
REST 해당 기능이 없습니다. 호환되는 커넥터를 사용할 수 있으면 사용하고, 그 출력을 @hyperframes/core/figma의 순수 헬퍼에 전달하세요; 그렇지 않으면 네이티브 익스포트를 요청하세요:
- 상위 프레임에 대한 모션 컨텍스트를 요소당 하나의 요청이 아닌 하나의 재귀 요청으로 검색하세요. 원시 JSON을 프로젝트 옆에 저장하세요 (
.media/figma-cache/) 재번역이 무료가 되도록. MotionDoc으로 정규화하려면@hyperframes/core/figma의motionContextToDocs(rawResponse, { selectorFor, repeat })를 사용하세요 — 키프레임 번호를 수동으로 기록하지 마세요. 헬퍼는 현장 테스트된 디코딩 규칙을 기계적으로 인코딩합니다: motion.dev 스니펫(신뢰할 수 있는 인코딩 — CSS 스니펫은 기간을 늘리고 불일치할 수 있습니다. 무시됨)을 구문 분석하고, 루프 래프 테일 키프레임(약 ≈0.9999→1 시간의 서브 밀리초 세그먼트는 루프의 즉시 재설정이며, 작성된 모션이 아닙니다 — 랩은repeat재시작에 의해 실현됨)을 제거하며, 베지어 이징을 그대로 보존합니다.selectorFor는 Phase-3 컴포넌트 가져오기의 ID를 반환해야 합니다 — 노드 이름에서 선택기를 파생시키지 마세요. 2b. 완료라고 부르기 전에 기준 진실과 비교하여 검증하세요 — 필수: 사용 가능한 커넥터를 통해 코호트의 루트 프레임을 내보내고node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y를 실행하세요 — 모션 에너지 델타(정적 가져오기 충실도는 상쇄됨)를 비교하고 최소 모션-PSNR이 15dB 미만이면 실패합니다 (보정됨: 정확함 ≈ 20+, 발산 ≈ 5).--crop을 렌더의 실제 카드 가장자리에서 측정하고 추측하지 마세요. FAIL은 임계값이 아닌 번역을 다시 확인하는 것을 의미합니다.motionToGsap(doc)→emitTimelineScript(spec)→ GSAP + CustomEase CDN 태그 뒤에<script>로 삽입합니다. 일시 중지되고, 유한하며, 리터럴 키로window.__timelines에 등록됩니다.- 번역 불가능한 트랙(셰이더 구동, 지원되지 않는 속성, 복잡한 마스크) → 커넥터를 통해 내보내고, MP4를 동결한 다음
<video class="clip">로 포함하세요. 예외: 셰이더 구동 트랙 — Figma의 내보내기 경로는 셰이더를 기본 색상으로 평면화하므로(아래 셰이더 참조), 거기서 베이크하면 자동으로 셰이더가 손실됩니다. 대신 사용자에게 네이티브 Figma 내보내기를 요청하세요. 항상 어떤 경로를 사용했는지와 그 이유를 말하세요. 매핑된 세트 외부의 명명된 이징은 선형으로 대체됩니다 — 매핑 테이블은motionEase.ts에 있습니다; 대체가 발생하면 사용자에게 플래그를 지정하세요. - 완료라고 부르기 전에
npx hyperframes check를 실행하세요.
셰이더 (Phase 5 — 대부분 수동)
Figma의 커넥터 렌더 경로는 셰이더를 실행하지 않습니다 (기본 색상으로 평면화됨). 셰이더 소스는 라이브러리 게시 스타일(유료 Full 시트)에만 도달할 수 있습니다. 기본 경로: 사용자에게 Figma에서 셰이더 프레임을 네이티브로 내보내도록(PNG 또는 모션 MP4) 요청한 다음, Phase-1 에셋 / 클립으로 가져오세요. 셰이더의 커넥터 픽셀 캡처를 시도하지 마세요 — 자동으로 잘못된 결과를 생성합니다.
스토리보드 (장면 프레임의 SECTION → 애니메이션)
핵심 규칙: 스토리보드 프레임은 키프레임이지 슬라이드가 아닙니다. 동일한 요소를 포함하는 두 프레임은 시간에 따른 해당 요소의 상태를 설명합니다 — 상태 간에 ELEMENT를 애니메이션화하세요. (이하 생략)