먼저, 이 스킬을 최신 상태로 유지하십시오 — 실행 전 사용자에게 확인:
npx hyperframes skills update figma. 모든 것이 최신 상태이면 빠르게 완료되고, 그렇지 않으면 이 스킬과 의존하는 핵심 도메인 스킬을 새로 고칩니다.
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 커넥터가 선택 사항으로 제공됩니다. 커넥터가 없으면 기본 내보내기를 요청하십시오. 모든 경로는 에셋을 로컬에 고정(freeze)하여 렌더링의 결정론성을 보장합니다. 스토리보드 재구성은 1단계 에셋 내보내기(REST)와 에이전트 주도 타임라인 조립을 결합하므로 커넥터가 필요하지 않습니다. 기존 고정 에셋, 매니페스트 레코드 및 바인딩은 라우팅 변경에 영향을 받지 않습니다 — 분할은 다음 가져오기에서 사용할 자격 증명만 변경합니다.
인증 — 두 가지 자격 증명, 범위 지정
사전 점검 — 첫 CLI 호출 전, 토큰 존재 여부 확인: 셸 환경 변수 ([ -n "$FIGMA_TOKEN" ]) 또는 프로젝트 .env 파일 (CLI가 자동 로드 — .env 항목은 구성된 것으로 간주). 둘 다 없으면 오류를 캐치하기 위해 명령을 실행하지 말고, 먼저 원타임 설정을 사용자에게 안내한 후 중지하고 대기하십시오:
- figma.com/settings → Security → Personal access tokens → 새 토큰 생성.
- 범위 — 이 통합에 필요한 것은 항상 읽기 전용입니다 (Figma에 쓰기 작업 없음): File content: Read-only + File metadata: Read-only. Enterprise 요금제가 아닌 경우
tokens를 실행하려면 Library content: Read-only를 추가하십시오 — 게시된 스타일 대체 경로가/v1/files/:key/styles를 호출하는데, 이 범위가 없으면 403 오류가 발생합니다 (이전 설정 텍스트에서 누락된 범위). 브랜드 변수에는 선택적으로 Variables: Read-only — Enterprise 전용입니다. 범위가 없으면tokens명령이 자동으로 게시된 스타일로 단계적으로 처리됩니다 (예상된 동작이며 오류가 아닙니다 — 그렇게 알리십시오). 403 오류는 정확히 어떤 범위가 누락되었는지 명시합니다. 429 오류는 자동으로 재시도됩니다 (분당 한도,Retry-After준수). - 사용자가 셸 프로필 또는 프로젝트
.env에FIGMA_TOKEN을 설정하도록 하십시오. 대화에 토큰을 붙여넣도록 요청하지 마십시오.
온보딩 중에는 다음 기대치를 한 번에 설명하십시오: 모든 가져오기는 기록된 출처가 있는 로컬 고정 파일로 저장됩니다 — 렌더링은 Figma를 다시 호출하지 않으며, 명령을 다시 실행하면 Figma에서 변경된 내용만 다시 가져오고, 하나의 토큰으로 사용자의 Figma 계정에서 볼 수 있는 모든 파일의 에셋, 브랜드 토큰 및 컴포넌트에 액세스할 수 있습니다.
- 단계 4–5 (모션/셰이더): 호환 가능한 Figma 커넥터를 사용하며, 토큰과는 별도의 인증이 필요합니다. 커넥터를 사용할 수 없거나 인증되지 않은 경우, 사용자에게 커넥터를 연결하거나 기본 내보내기를 제공하도록 요청한 후 중지하십시오.
- 실패하는 단계에 정확히 어떤 자격 증명이 필요한지 명시하십시오 — 분할이 잘못되었다고 제시하지 마십시오.
BAD_TOKEN(401) 중간 발생 → 토큰이 만료/취소되었습니다. 새로 발급받으십시오.FORBIDDEN(403) → 메시지에 정확히 누락된 범위가 명시됩니다 (예: 스타일 대체 경로의 경우library_content:read) — 범위를 추가하거나 파일을 계정에서 볼 수 없습니다.REQUIRES_ENTERPRISE(변수에서 403) → 오류가 아닙니다: 스타일 대체 경로가 이미 실행되었습니다.RATE_LIMITED(429) → 클라이언트가 이미 백오프와 함께 재시도했습니다 (이것은 에셋, 토큰, 스타일, 노드 트리, 버전 등 모든 읽기 요청에 적용됩니다 — 재시도는 공유 요청 경로에 있습니다;Retry-After를 준수하며 최대 60초로 제한됨). 그럼에도 표시되면 잠시 기다리거나 호출당 노드 수를 줄이십시오.
속도 제한 인식 (명세 §2.1): 커넥터 할당량은 Figma 요금제에 따라 다릅니다 — 부모 프레임 요청을 일괄 처리하고, 요청하지 않은 확인 스크린샷은 건너뛰며, 원시 응답을 캐시하여 재처리 시 추가 호출이 발생하지 않도록 하십시오. REST는 분당입니다 (분당 10개 이상, 엔드포인트별 버킷) — 대량 처리에 적합하며 429 발생 시 백오프합니다.
라우팅
parseFigmaRef를 사용하여 사용자의 Figma 링크를 파싱합니다 (URL, fileKey:nodeId, fileKey 단독). 그런 다음 의도에 따라:
- "이 레이어 / 로고 / 이미지 사용" → 에셋 (CLI)
- "내 브랜드 / 색상 / 토큰 가져오기" → 토큰 (CLI)
- "이 프레임에서 장면 만들기" → 컴포넌트 (CLI)
- "이 애니메이션 / 모션 가져오기" → 모션 (가능한 경우 커넥터 사용, 아래 참조)
- 스토리보드 섹션 / 장면 프레임 필름스트립 → 스토리보드 (아래 참조)
- 셰이더 채우기/효과 → 셰이더 (아래 참조)
모든 단계를 사용자에게 설명하십시오 — 각 명령 전에 Figma에서 무엇을 가져올 것인지 말하고, 명령 후에는 아티팩트가 저장된 위치 (고정 경로 / 사이드카 / 컴포넌트 디렉토리), 컴포지션에서 변경된 사항, 그리고 즉시 수행할 다음 작업 (미리보기, 인쇄 변수 추가, 바인딩 연결을 위한 재가져오기)을 알리십시오. 사용자가 "제대로 작동했나요?" 또는 "이제 무엇을 해야 하나요?"라고 묻게 해서는 안 됩니다.
에셋 (1단계 — CLI)
hyperframes figma asset '<url-or-fileKey:nodeId>' [추가 refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
REST를 통해 렌더링하고, SVG를 살균하며, .media/images/ 아래에 고정하고, 출처와 함께 매니페스트에 추가하며, .media/index.md (공유 미디어 사용 인벤토리)를 재생성하고, <img> 스니펫을 출력합니다. fileKey:nodeId:format:scale:version 별로 멱등성을 보장합니다. 벡터/로고에는 SVG (확장 가능, 애니메이션 가능)를 선호하고, 래스터 충실도에는 --scale 2와 함께 PNG를 선호합니다. 항상 --description "<설명>"을 전달하십시오 (인덱스 행 + <img alt>가 됩니다); 명명된 브랜드 마크에는 --entity "<이름>"을 추가하여 미디어 사용 resolve --entity가 나중에 찾을 수 있도록 하십시오 (엔터티 일치는 이미지/아이콘 전체에서 발생합니다).
여러 노드를 하나의 요청으로 일괄 처리하십시오 — 동일한 파일의 여러 ref를 전달하십시오 (공백 또는 쉼표로 구분): hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. 모든 노드가 단일 /v1/images 호출로 렌더링되며, 이는 분당 속도 제한에 대한 Figma 자체의 답변입니다 — 전체 프레임의 에셋을 가져올 때는 N개의 개별 명령보다 일괄 처리를 선호하십시오. --description/--entity는 배치의 모든 노드에 적용되므로, 같은 목적을 공유하는 노드를 배치로 묶으십시오. 429 오류도 백오프와 함께 자동 재시도됩니다.
토큰 (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(--슬러그, 리터럴) 채우기는 변수 기본값이 변경될 때 다시 칠합니다. data-composition-variables에서 값을 업데이트하면, 다시 가져오지 않고도 모든 가져온 컴포넌트가 리브랜딩됩니다. hyperframes render --variables '<json>'는 렌더링 시 이를 재정의합니다.
컴포넌트 (3단계 — CLI)
hyperframes figma component '<url-or-fileKey:nodeId>'
노드 트리 → 정확한 Figma 지오메트리의 편집 가능한 HTML로, compositions/components/<name>/ 아래의 레지스트리 항목으로 패키징됩니다. 벡터/부울 연산은 1단계 내보내기를 통해 자동 래스터화됩니다. 바인딩 패스 (명세 §7.1, 정확한 ID만 — 값 일치 금지):
- 정적 충실도 자체 점검 (주요 콘텐츠에 필수): 가져온 후, 프래그먼트를 렌더링하고 Figma 자체 픽셀과 비교하십시오 —
figma asset <동일 노드> --format png가 기준점입니다. 텍스트는 알려진 편차 축입니다: 줄 높이보다 짧은 Figma 텍스트 상자는 수직으로 잘린 경계를 가집니다 (매퍼는 이 경우text-box-trim을 내보냅니다; 이 규칙 없이 측정된 편차는 70px 폰트에서 약 6px였습니다). 비교 결과 매퍼가 다루지 않는 편차가 발견되면 보고하십시오 — 프래그먼트를 자동으로 수정하지 마십시오. - 가져온 토큰에 바인딩된 채우기 →
var(--슬러그, #리터럴)— 브랜드 새로고침이 전파됩니다. - 알 수 없는 토큰에 바인딩된 채우기 → 리터럴 +
data-figma-unresolved플래그. 명령이 알려줍니다. 사용자에게 다음을 제안하십시오: 소스 (또는 라이브러리) 파일에서tokens를 실행한 다음 컴포넌트를 다시 가져와 연결합니다. 알 수 없는 라이브러리에 대해 한 번만 어떤 파일인지 물어보십시오 — 추측하지 말고, 헥스 값으로 일치시키지 마십시오.
모션 (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/)에 저장하여 재변환이 무료로 이루어지도록 하십시오. @hyperframes/core/figma에서motionContextToDocs(rawResponse, { selectorFor, repeat })를 사용하여MotionDoc으로 정규화하십시오 — 키프레임 번호를 수동으로 기록하지 마십시오. 헬퍼는 기계적으로 현장 테스트된 디코딩 규칙을 인코딩합니다: motion.dev 스니펫 (신뢰할 수 있는 인코딩 — CSS 스니펫은 지속 시간을 늘리고 불일치할 수 있으므로 무시됨)을 구문 분석하고, 루프 랩 테일 키프레임 (시간 ≈0.9999→1의 서브밀리초 세그먼트는 루프의 즉각적인 재설정이므로 작성된 모션이 아님 — 랩은repeat재시작으로 구현됨)을 제거하며, 베지어 이징을 그대로 유지합니다.selectorFor는 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을 렌더링의 실제 카드 가장자리에서 측정하고 추측하지 마십시오. 실패는 임계값이 아니라 변환을 다시 확인해야 함을 의미합니다.motionToGsap(doc)→emitTimelineScript(spec)→ GSAP + CustomEase CDN 태그 뒤에<script>로 삽입합니다. 일시 중지되고, 유한하며, 리터럴 키와 함께window.__timelines에 등록됩니다.- 변환할 수 없는 트랙 (셰이더 구동, 지원되지 않는 속성, 복잡한 마스크) → 커넥터를 통해 내보내고, MP4를 고정한 다음
<video class="clip">로 포함합니다. 예외: 셰이더 구동 트랙 — Figma의 내보내기 경로는 셰이더를 기본 색상으로 평면화하므로 (아래 셰이더 참조), 그곳에서 베이크하면 조용히 셰이더가 손실됩니다. 대신 사용자에게 Figma 기본 내보내기를 요청하십시오. 항상 어떤 경로를 사용했는지와 그 이유를 말하십시오. 매핑된 세트 외부의 명명된 이징은 선형으로 대체됩니다 — 매핑 테이블은motionEase.ts에 있습니다. 발생 시 사용자에게 대체를 알리십시오. - 완료 전에
npx hyperframes check를 실행하십시오.
셰이더 (5단계 — 대부분 수동)
Figma의 커넥터 렌더 경로는 셰이더를 실행하지 않습니다 (기본 색상으로 평면화됨). 셰이더 소스는 라이브러리 게시된 스타일 (유료 풀 시트)인 경우에만 접근 가능합니다. 기본 경로: 사용자에게 Figma에서 셰이더 프레임을 기본 내보내기(PNG 또는 모션 MP4)하도록 요청한 다음, 1단계 에셋/클립으로 가져오십시오. 셰이더의 커넥터 픽셀 캡처를 시도하지 마십시오 — 잘못된 결과를 조용히 생성할 것입니다.
스토리보드 (장면 프레임 섹션 → 애니메이션)
핵심 규칙: 스토리보드 프레임은 키프레임이지 슬라이드가 아닙니다. 동일한 요소를 포함하는 두 프레임은 시간에 따른 해당 요소의 상태를 설명합니다 — 상태 간에 ELEMENT를 애니메이션 처리합니다. 프레임을 연속적인 스틸 시퀀스로 재생하지 마십시오. 네 개의 연속된 프레임에 y가 감소하며 그려진 로고는 네 개의 키프레임을 통해 위로 올라가는 하나의 요소입니다. 스토리보드 프레임을 연속해서 재생하는 것은 실패 모드입니다. 그것들이 암시하는 요소 타임라인을 재구성하는 것이 작업입니다.
스토리보드 파일은 기계적으로 구문 분석할 수 있는 문법을 따릅니다 — 육안으로 확인하지 말고 디코딩하십시오:
- 장면 단위: SECTION 내부에서, 프레임 크기의 모든 노드는 장면입니다 — 명명된 FRAME 그리고 느슨한 전체 프레임 RECTANGLE (디자이너가 스틸을 섹션에 직접 붙여넣습니다). 노드 유형이나 이름이 아니라 크기로 필터링하십시오 (≈ 컴포지션 종횡비, 예: >1400×900).
- 순서 = x-위치 (스트립이 줄바꿈되면 행 우선).
absoluteBoundingBox.x로 장면을 정렬합니다. - 인접 프레임을 요소 체인으로 차분 — 여기에 애니메이션이 있습니다. 연속된 프레임 간에 자식을 일치시킵니다: 먼저 이름 (같은 이름 = 같은 요소 → 상태 간 상대적 x/y/w/h를 트윈), 그런 다음 지오메트리 유사성 (유사한 크기와 위치, 예: 90% IoU 중첩 — 이것은 디자이너가 로고를 다시 배치했지만 사본으로 간주되었을 때를 포착합니다). 편집된 하위 항목이 동일한 부모 아래에 나타나면 체인이 분할되는 것으로 처리하십시오 — 두 하위 체인을 끝까지 추적하고 두 결과 타임라인을 모두 방출하십시오.
구현:
# 의사 코드 — 해석 지침
element_chains = []
for scene_a, scene_b in zip(scenes, scenes[1:]):
matched = match_children(scene_a, scene_b)
for child_id, child_b in matched:
chain = element_chains.find_or_create(child_id)
chain.add_keyframe(state_from(child_a), state_from(child_b))
- 각 체인을
slide_createTransform()호출 체인으로 변환하고 지속 시간을 균등하게 분배하십시오 (한 프레임에서 다른 프레임으로의 전환은 동일한 지속 시간을 가져야 함 — 그렇지 않으면 불연속성이 발생합니다). 장면 시작 시간이 스토리보드에 의해 정의되지 않은 경우 (FILMSTRIP에 타임스탬프 없음), 지속 시간을 장면 간 간격의 1/장면 수로 설정하지만, GSAP 타임라인 오프셋 == 장면 간격(× 반복 등)이 아닌 장면 간격(스토리보드 단위)이 되도록 하십시오. - 스토리보드 전체에 걸쳐 요소 타임라인을 방출한 후, 출력을 연결하고 구성요소는 전혀 방출하지 않고 (장면 프레임은 요소 수가 아니라 요소 타임라인을 통해 재생됩니다)
window.__timelines에 등록하십시오. 방출된 타임라인은 스토리보드 시작 시 처음부터 끝까지 재생되며, 사용자가 개별 장면을 건너뛰거나 클릭할 필요가 없습니다.
CLI 개요
대부분의 상호 작용은 hyperframes figma asset, hyperframes figma tokens, hyperframes figma component를 통해 이루어집니다. 각 명령은 결과를 설명하고 다음 단계를 제안합니다. 하나의 명령이 다른 명령에 의존하는 경우 (예: 토큰 후 컴포넌트), 명령이 이를 감지하고 미리 알려줍니다.
일반 요구 사항
FIGMA_TOKEN환경 변수 (또는 프로젝트.env파일에 설정).- Node.js 및
hyperframesCLI가 설치되어 있어야 합니다. - 모션 및 셰이더 단계에는 선택적으로 호환 가능한 Figma 커넥터가 필요할 수 있습니다.