courtneymgabrus-star/Video

플러그인 설치: 설정 또는 갱신 명령 전, 이 스킬이 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 항목이 구성된 것으로 간주됨). 둘 다 없으면 오류를 수집하기 위해 명령을 실행하지 말고 — 사용자에게 일회성 설정을 안내한 다음 중지하고 기다리십시오:

1. figma.com/settings → Security → Personal access tokens → Generate new token.
2. 범위 — 이 통합에 필요한 것은 읽기 전용뿐입니다 (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 준수).
3. 사용자가 셸 프로필 또는 프로젝트 .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 (URL, fileKey:nodeId, bare fileKey)를 사용하여 사용자의 Figma 링크를 구문 분석하십시오. 그런 다음 의도에 따라:

• "이 레이어 / 로고 / 이미지 사용" → 에셋 (CLI)
• "내 브랜드 / 색상 / 토큰 가져오기" → 토큰 (CLI)
• "이 프레임에서 장면 만들기" → 컴포넌트 (CLI)
• "이 애니메이션 / 모션 가져오기" → 모션 (사용 가능한 경우 커넥터, 아래 참조)
• 스토리보드 섹션 / 장면 프레임의 필름스트립 → 스토리보드 (아래 참조)
• 셰이더 채우기/효과 → 셰이더 (아래 참조)

사용자를 위해 모든 단계를 설명하십시오 — 각 명령 전에 Figma에서 무엇을 가져올 것인지 말하고, 명령 후에 아티팩트가 어디에 배치되었는지 (동결 경로 / 사이드카 / 컴포넌트 디렉토리), 컴포지션에서 무엇이 변경되었는지, 그리고 다음 즉시 실행할 작업 (미리보기, 인쇄된 변수 추가, 바인딩 연결을 위한 재가져오기)을 말하십시오. 사용자는 "작동했나요?" 또는 "이제 뭐죠?"라고 묻지 않아야 합니다.

에셋 (1단계 — CLI)

hyperframes figma asset '<url-or-fileKey:nodeId>' [다른 참조…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

REST를 통해 렌더링하고, SVG를 살균하고, .media/images/ 아래에 동결시키고, 매니페스트에 출처를 추가하고, .media/index.md (공유 미디어 사용 인벤토리)를 다시 생성하고, <img> 스니펫을 출력합니다. fileKey:nodeId:format:scale:version별로 멱등합니다. 벡터/로고에는 SVG (확장 가능, 애니메이션 가능)를, 래스터 충실도에는 PNG --scale 2를 선호합니다. 항상 --description "<설명>"을 전달하십시오 (인덱스 행 + <img alt>가 됩니다). 명명된 브랜드 마크에 대해 --entity "<이름>"를 추가하여 미디어 사용 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)로 가져옵니다. 변수는 상류에서 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, literal)은 변수 기본값이 변경될 때 다시 칠하기를 채웁니다 — 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, #literal) — 브랜드 새로 고침이 전파됩니다.
• 알 수 없는 토큰에 바인딩됨 → 리터럴 + 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의 순수 도우미에 전달하십시오. 그렇지 않으면 네이티브 내보내기를 요청하십시오:

1. 요소당 하나의 요청이 아닌 하나의 재귀 요청으로 상위 프레임의 모션 컨텍스트를 검색하십시오. 원시 JSON을 프로젝트 옆에 저장하십시오 (.media/figma-cache/) — 재번역이 무료입니다.
2. @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를 실행하십시오 — 모션 에너지 델타를 비교하고 (정적 가져오기 충실도는 상쇄됨) 15dB 최소 모션-PSNR 아래에서 실패합니다 (보정됨: 충실 ≈ 20+, 발산 ≈ 5). --crop을 렌더링의 실제 카드 가장자리에서 측정하고 추측하지 마십시오. FAIL은 임계값이 아니라 번역을 다시 확인해야 함을 의미합니다.
3. motionToGsap(doc) → emitTimelineScript(spec) → GSAP + CustomEase CDN 태그 뒤에 <script>로 주입하십시오. 일시 중지되고, 유한하며, 리터럴 키로 window.__timelines에 등록됩니다.
4. 번역 불가능한 트랙 (셰이더 기반, 지원되지 않는 속성, 복잡한 마스크) → 커넥터를 통해 내보내고, MP4를 동결시킨 다음 <video class="clip">로 포함시키십시오. 예외: 셰이더 기반 트랙 — Figma의 내보내기 경로는 셰이더를 기본 색상으로 평면화합니다 (아래 셰이더 참조). 따라서 거기서 베이크하면 조용히 셰이더가 손실됩니다. 대신 사용자에게 네이티브 Figma 내보내기를 요청하십시오. 항상 어떤 경로를 사용했는지와 그 이유를 말하십시오. 매핑된 세트 외부의 명명된 이징은 선형으로 대체됩니다 — 매핑 테이블은 motionEase.ts에 있습니다. 발생 시 사용자에게 대체를 알리십시오.
5. 완료하기 전에 npx hyperframes check를 실행하십시오.

셰이더 (5단계 — 대부분 수동)

Figma의 커넥터 렌더링 경로는 셰이더를 실행하지 않습니다 (기본 색상으로 평면화됨). 셰이더 소스는 라이브러리에 게시된 스타일 (유료 Full 시트)에 대해서만 도달할 수 있습니다. 기본 경로: 사용자에게 Figma에서 셰이더 프레임을 네이티브로 내보내도록 (PNG 또는 모션 MP4) 요청한 다음 1단계 에셋/클립으로 가져오십시오. 셰이더의 커넥터 픽셀 캡처를 시도하지 마십시오 — 조용히 잘못된 결과를 생성합니다.

스토리보드 (장면 프레임의 SECTION → 애니메이션)

핵심 규칙: 스토리보드 프레임은 키프레임이지 슬라이드가 아닙니다. 동일한 요소를 포함하는 두 개의 프레임은 시간에 따른 해당 요소의 상태를 설명합니다 — 상태 간에 ELEMENT를 애니메이션 처리하십시오. 프레임을 스틸의 시퀀스로 재생하지 마십시오. 내림차순 y의 4개 연속 프레임에 그려진 로고는 4개의 키프레임을 통해 올라가는 ONE 요소입니다. 스토리보드 프레임을 연속으로 재생하는 것은 실패 모드이며, 이들이 암시하는 요소 타임라인을 재구성하는 것이 작업입니다.

스토리보드 파일은 기계적으로 구문 분석할 수 있는 문법을 따릅니다 — 육안으로 확인하지 말고 디코딩하십시오:

1. 장면 단위: SECTION 내에서 모든 프레임 크기 노드는 장면입니다 — 명명된 FRAME 및 느슨한 전체 프레임 RECTANGLE (디자이너는 스틸을 섹션에 직접 붙여넣습니다). 노드 유형이나 이름이 아닌 크기(예: >1400×900의 컴포지션 종횡비)로 필터링하십시오.
2. 순서 = x-위치 (스트립이 줄 바꿈되면 행 우선). absoluteBoundingBox.x로 장면을 정렬하십시오.
3. 인접한 항목의 차이 계산

...