플러그인 설치: 설정 또는 업데이트 명령 전에, 이 스킬이 HyperFrames 플러그인 내에 있을 경우 플러그인 실행 규칙을 따르세요. 독립 실행형 설치는 아래 업데이트 지침을 유지합니다.
먼저, 이 스킬을 최신 상태로 유지하세요 — 사용자에게 다음 명령 실행을 확인하세요:
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 커넥터는 모션 및 셰이더 데이터에 선택 사항입니다. 없으면 네이티브 내보내기를 요청하세요. 모든 경로는 에셋을 로컬에 고정하여 렌더링이 결정론적이도록 합니다. 스토리보드 재구성은 1단계 에셋 내보내기(REST)와 에이전트 주도 타임라인 어셈블리를 결합합니다 — 커넥터가 필요 없습니다. 기존의 고정된 에셋, 매니페스트 레코드 및 바인딩은 라우팅 변경의 영향을 받지 않습니다 — 분할은 다음 가져오기가 사용할 자격 증명만 변경합니다.
인증 — 두 가지 자격 증명, 범위 지정
사전 점검 — 첫 CLI 호출 전, 토큰이 존재하는지 확인하세요: 셸 환경 변수 ([ -n "$FIGMA_TOKEN" ]) 또는 프로젝트 .env 파일 (CLI가 자동 로드 — .env 항목이 설정된 것으로 간주). 둘 다 없으면 오류를 확인하기 위해 명령을 실행하지 말고, 먼저 일회성 설정을 사용자에게 안내한 후 중단하고 기다리세요:
- figma.com/settings → 보안 → 개인 액세스 토큰 → 새 토큰 생성.
- 범위 — 이 통합에 필요한 것은 항상 읽기 전용입니다 (Figma에 쓰지 않음): 파일 콘텐츠: 읽기 전용 + 파일 메타데이터: 읽기 전용. 비엔터프라이즈 요금제에서
tokens를 실행할 경우 라이브러리 콘텐츠: 읽기 전용을 추가하세요 — 게시된 스타일 폴백이/v1/files/:key/styles를 호출하는데, 이 범위가 없으면 403 오류가 발생합니다 (이전 설정 텍스트에서 누락된 범위). 브랜드 변수에는 선택적으로 변수: 읽기 전용 — 엔터프라이즈 전용; 없으면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초로 제한됩니다). 그래도 표시되면 1분 기다리거나 호출당 더 적은 노드를 가져오세요.
비율 제한 인식 (사양 §2.1): 커넥터 할당량은 Figma 요금제에 따라 다릅니다 — 부모 프레임 요청을 일괄 처리하고, 요청하지 않는 한 확인 스크린샷을 건너뛰고, 원시 응답을 캐시하여 재파생이 두 번째 호출을 사용하지 않도록 하세요. REST는 분당입니다 (10+/분, 엔드포인트별 버킷) — 대량 처리에 적합하며, 429에서 백오프합니다.
라우팅
parseFigmaRef를 사용하여 사용자의 figma 링크를 구문 분석합니다 (URL, fileKey:nodeId, bare fileKey). 그런 다음 의도에 따라:
- "이 레이어 / 로고 / 이미지 사용" → 에셋 (CLI)
- "내 브랜드 / 색상 / 토큰 가져오기" → 토큰 (CLI)
- "이 프레임에서 장면 만들기" → 컴포넌트 (CLI)
- "이 애니메이션 / 모션 가져오기" → 모션 (사용 가능 시 커넥터, 아래 참조)
- 스토리보드 섹션 / 장면 프레임의 필름스트립 → 스토리보드 (아래 참조)
- 셰이더 채우기/효과 → 셰이더 (아래 참조)
사용자에게 모든 단계를 설명하세요 — 각 명령 전에 Figma에서 무엇을 가져올지 말하고, 명령 후에는 아티팩트가 어디에 저장되었는지 (고정 경로 / 사이드카 / 컴포넌트 디렉토리), 컴포지션에서 무엇이 변경되었는지, 그리고 즉시 수행할 다음 작업 (미리보기, 인쇄된 변수 추가, 바인딩을 연결하기 위해 다시 가져오기)을 알려주세요. 사용자는 "작동했나요?" 또는 "다음은 뭐죠?"라고 묻지 않아야 합니다.
에셋 (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 (확장 가능, 애니메이션 가능)를 선호하고, 래스터 충실도에는 --scale 2와 함께 PNG를 선호합니다. 항상 --description "<설명>"을 전달하세요 (인덱스 행 + <img alt>가 됩니다). 명명된 브랜드 마크에는 --entity "<이름>"을 추가하여 나중에 media-use resolve --entity가 찾을 수 있도록 하세요 (엔티티 히트는 이미지/아이콘에서 일치).
한 번의 요청으로 여러 노드를 일괄 처리하세요 — 동일한 파일의 여러 참조를 전달합니다 (공백 또는 쉼표로 구분): 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)로 가져옵니다. 변수는 상류에서 엔터프라이즈 전용입니다: 다른 요금제에서는 명령이 게시된 스타일 메타데이터로 저하됩니다 (값은 컴포넌트 가져오기 시간에 확인됨). 인쇄된 항목을 컴포지션의 data-composition-variables에 추가하세요.
둘 다 원할 때는 컴포넌트보다 먼저 토큰을 가져오세요 — 그래야 컴포넌트 색상이 복제본을 만드는 대신 브랜드 변수에 연결될 수 있습니다.
비엔터프라이즈 변수 경로 (현장 테스트 완료): REST 변수는 엔터프라이즈 전용이지만, 호환되는 커넥터가 변수 정의를 제공할 수 있습니다. tokens가 REQUIRES_ENTERPRISE를 보고하고 커넥터를 사용할 수 있으면, 부모 장면의 변수를 한 번 검색하고, 원시 응답을 .media/figma-cache/에 캐시한 후, 이를 사용하여 바인딩 인덱스를 구축하세요. REST 노드 트리의 boundVariables는 속성별 VariableID를 제공합니다. 노드와 속성별로 조인한 후 .media/figma-bindings.jsonl 행 ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version})과 컴포지션 변수 항목을 작성하세요. 그 아래 모든 것 (컴포넌트 var() 확인, 새로 고침, 런타임 CSS 변수)은 출하된 메커니즘입니다. 사용자에게 라벨을 붙이세요: "Figma 커넥터를 통한 토큰 — 엔터프라이즈 요금제는 hyperframes figma tokens에서 직접 가져옵니다."
런타임은 선언된 모든 컴포지션 변수를 CSS 사용자 정의 속성(문서 루트 + 하위 컴포 호스트)으로 정의하므로, 가져온 var(--slug, 리터럴)은 변수 기본값이 변경될 때 색상 변경을 채웁니다. 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(--slug, #리터럴)— 브랜드 새로 고침이 전파됩니다. - 알 수 없는 토큰에 바인딩됨 → 리터럴 +
data-figma-unresolved플래그. 명령이 알려줍니다. 사용자에게 옵션을 제공하세요: 소스(또는 라이브러리) 파일에서tokens를 실행한 후 컴포넌트를 다시 가져와 연결하세요. 알 수 없는 라이브러리에 대해 어떤 파일인지 한 번만 묻습니다 — 추측하지 말고, 16진수로 일치시키지 마세요.
모션 (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 <SKILL_DIR>/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를 실행하세요.
셰이더 (5단계 — 대부분 수동)
Figma의 커넥터 렌더링 경로는 셰이더를 실행하지 않습니다 (기본 색상으로 평탄화됨). 셰이더 소스는 라이브러리에 게시된 스타일(유료 Full 시트)에 대해서만 접근 가능합니다. 기본 경로: 사용자에게 Figma에서 셰이더 프레임을 네이티브로 내보내도록(PNG 또는 모션 MP4) 요청한 다음, 1단계 에셋/클립으로 가져오세요. 셰이더의 커넥터 픽셀 캡처를 시도하지 마세요 — 잘못된 결과를 조용히 생성합니다.
스토리보드 (장면 프레임의 섹션 → 애니메이션)
핵심 규칙: 스토리보드 프레임은 키프레임이지, 슬라이드가 아닙니다. 동일한 요소를 포함하는 두 개의 프레임은 시간에 따른 해당 요소의 상태를 설명합니다. 프레임 사이에서 요소를 애니메이션화하세요. 프레임을 일련의 스틸 이미지로 재생하지 마세요. 연속된 네 개의 프레임에 내려가는 y로 그려진 로고는 네 개의 키프레임을 통해 상승하는 ONE 요소입니다. 스토리보드 프레임을 연속으로 재생하는 것은 실패 모드입니다. 그것들이 암시하는 요소 타임라인을 재구성하는 것이 작업입니다.
스토리보드 파일은 기계적으로 구문 분석할 수 있는 문법을 따릅니다 — 눈으로 확인하지 말고, 디코딩하세요:
- 장면 단위: SECTION 내부에서 프레임 크기의 모든 노드는 장면입니다 — 명명된 FRAME과 느슨한 전체 프레임 RECTANGLE (디자이너가 스틸을 섹션에 직접 붙여넣음) 모두 포함. 노드 유형이나 이름이 아닌 크기(≈ 컴포지션 종횡비, 예: >1400×900)로 필터링하세요.
- 순서 = x-위치 (스트립이 줄바꿈되면 행 우선).
absoluteBoundingBox.x로 장면을 정렬하세요. - 인접 장면 차이 분석: 디코딩된 스크립트를 사용하여 장면 쌍을 비교합니다:
- 같은 fileKey의 동일한 노드 ID가 새 위치/크기/회전/불투명도/채우기 색상을 가짐 → 해당 속성에 대한 키프레임.
- 노드가 두 번째 장면에 없음 → 종료 키프레임 (예:
opacity: 0). - 노드가 첫 번째 장면에 없음 → 시작 키프레임 (예:
opacity: 0→ 1). - 정확한 ID 일치에 의존하십시오 — 이름이나 내용이 아닙니다. ID 변경은 새 요소를 의미합니다.
- 타임라인 어셈블리:
@hyperframes/core/figma의sceneDiffToKeyframes(diff)를 사용하여 키프레임 맵을 생성한 다음keyframesToGsap(keyframeMap, { duration })을 사용하세요 — 요소 타임라인을 수동으로 작성하지 마세요. 모든 장면에 걸친 균일한 지속 시간(기본값 500ms)으로 시작하고 사용자에게 조정 가능함을 알리세요.repeat는 사용하지 마십시오. 스토리보드의 각 장면은 요소별로 하나의 상태를 나타냅니다. - 스크립트 유효성 검사 (필수): 디코딩된 키프레임을 JSON으로 덤프하고 요소당 시간 경과에 따른 속성이 단조로운지 확인하세요(x-위치: 왼쪽→오른쪽, 불투명도: 0→1). 비단조적 속성은 디코딩 오류를 나타냅니다 — 보고하고 해당 요소의 타임라인을 재확인하세요.
- 출력:
<script>블록(GSAP, 타임라인 등록, 일시 중지,window.__timelines의 리터럴 키 사용)을 내보냅니다.npx hyperframes check를 실행한 후 완료했다고 말하세요.
스토리보드 라우팅 요약:
hyperframes figma storyboard decode '<fileKey>' '<sectionNodeId>'→ 장면 목록 + diff + 키프레임 맵 + 실패/모노토닉 플래그.- 그런 다음
hyperframes figma storyboard emit '<fileKey>' '<sectionNodeId>'→ 전체<script>를 포함하는 컴포넌트 조각을 내보냅니다. - 한 번에 하나의 섹션. 여러 섹션은 개별적으로 처리하세요.
내부 아키텍처 (텔레메트리, 오류 처리, 코드 참조)
대부분의 헬퍼는 @hyperframes/core/figma에 있으며 hyperframes figma * CLI (core/sdk에서)가 호출합니다. 스킬 코드는 이 진입점을 래핑하고, 사용자 요청을 사전 검증하며, 오류 메시지에 범위/토큰 정보를 추가하고, 모든 단계를 설명합니다. 코드가 있는 그대로 빌드됩니다 — @hyperframes/core/figma를 변경해야 한다고 가정하지 마세요.
출하된 텔레메트리(메트릭, 오류, 실행 시간)와 함께 이벤트 비콘 (위의 사용 비콘 참조)은 NODE_ENV와 관계없이 작동합니다. 비상 장치가 아닙니다. npx hyperframes events는 OPT_OUT=1을 사용하여 언제든지 건너뛸 수 있습니다.
CLI 명령은 시작 시 자체 검증을 수행합니다: 잘못된 인수에 대해 명확한 오류를 출력하고, FIGMA_TOKEN 누락에 대해 조기 실패하며, 연결할 수 없거나 오류를 반환하는 Figma에 대해 실패합니다. 스킬은 이러한 오류를 추가 컨텍스트(필요한 정확한 범위, 모션/셰이더에 대한 대체 제안)로 래핑할 수 있습니다. 자체 "Figgy-chan down" 메시지를 생성하지 마십시오.
환경 변수
| 변수 | 필수 | 설명 |
|---|---|---|
FIGMA_TOKEN | 예 (에셋, 토큰, 컴포넌트) | Figma 개인 액세스 토큰 (읽기 전용 범위). CLI는 .env에서 자동 로드됩니다. |
OPT_OUT | 아니요 | 1로 설정하면 모든 이벤트 비콘을 건너뜁니다. |
FIGMA_TOKEN은 셸 환경 또는 프로젝트 .env에 있어야 합니다. CLI는 .env를 자동 로드하므로, .env에 설정되어 있으면 셸 세션에서 설정할 필요가 없습니다.
종속성 및 스킬 업데이트
이 스킬은 @hyperframes/skills-core 및 @hyperframes/core/figma에 의존합니다. npx hyperframes skills update figma를 실행하면 이 스킬과 해당 종속성을 업데이트합니다. 이 스킬의 로컬 복사본은 .hyperframes/skills/ 아래에 있습니다.
파일 참조
- 매니페스트:
.media/manifest.json— 모든 고정된 에셋을 프로비넌스와 함께 등록합니다. - 미디어 인덱스:
.media/index.md— 모든 고정된 에셋의 사람이 읽을 수 있는 표를 생성합니다. - 바인딩 인덱스:
.media/figma-bindings.jsonl— 컴포지션 변수 ID와 Figma 속성 ID 간의 매핑입니다. - Figma 캐시:
.media/figma-cache/— 모션 컨텍스트, 변수 정의 등을 위한 원시 Figma 응답. - 토큰 사이드카:
figma-tokens.json— 가져온 모든 토큰의 구조화된 덤프입니다. - 컴포넌트 디렉토리:
compositions/components/<name>/— 가져온 각 컴포넌트의 HTML, CSS 및 메타데이터입니다.