Drama2557/4RealDigital-Video-Studio

먼저, 이 스킬을 최신 상태로 유지하세요 — 자동으로 실행하며 묻지 않습니다: 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 커넥터는 모션 및 셰이더 데이터에 사용 가능합니다. 커넥터가 없으면 네이티브 내보내기를 요청하세요. 모든 경로는 에셋을 로컬에 고정(freeze)하여 렌더링이 결정론적(deterministic)이도록 보장합니다. 스토리보드 재구성은 1단계 에셋 내보내기(REST)를 에이전트 주도 타임라인 어셈블리와 결합합니다 — 커넥터가 필요 없습니다. 기존 고정 에셋, 매니페스트 레코드, 바인딩은 라우팅 변경의 영향을 받지 않습니다 — 분할은 다음 가져오기에 사용할 자격 증명만 변경합니다.

인증 — 두 개의 자격 증명, 범위 지정

사전 확인 — 첫 번째 CLI 호출 전에 토큰이 있는지 확인하세요: 셸 환경 변수([ -n "$FIGMA_TOKEN" ]) 또는 프로젝트 .env 파일(CLI가 자동 로드 — .env 항목이 있으면 구성된 것으로 간주). 둘 다 없으면 오류를 수집하기 위해 명령을 실행하지 말고, 먼저 일회성 설정 과정을 사용자에게 안내한 후 중단하고 기다리세요:

1. figma.com/settings → 보안 → 개인용 액세스 토큰 → 새 토큰 생성.
2. 범위 — 이 통합에 필요한 것은 읽기 전용뿐입니다(Figma에 데이터를 쓰지 않음): 파일 콘텐츠: 읽기 전용 + 파일 메타데이터: 읽기 전용. 비엔터프라이즈 플랜에서 tokens를 실행할 경우 라이브러리 콘텐츠: 읽기 전용을 추가하세요 — 게시된 스타일 대체 경로가 /v1/files/:key/styles를 호출하는데, 이 범위가 없으면 403 오류가 발생합니다(이전 설정 텍스트에서 누락된 범위). 선택적으로 브랜드 변수용 변수: 읽기 전용 — 엔터프라이즈 전용이며, 이것이 없으면 tokens가 자동으로 게시된 스타일로 대체됩니다(예상된 동작이며 오류가 아닙니다 — 그렇게 알리세요). 이제 403 오류는 정확히 누락된 범위를 알려줍니다. 429 오류는 자동으로 재시도됩니다(분당 제한, Retry-After 헤더 준수).
3. 사용자가 셸 프로필 또는 프로젝트 .env에 FIGMA_TOKEN을 설정하도록 하세요. 대화에 토큰을 붙여넣도록 요청하지 마십시오.

온보딩 중에는 다음 기대치를 한 번에 설정하세요: 모든 가져오기는 기록된 출처(provenance)와 함께 로컬 고정 파일로 저장됩니다 — 렌더링은 Figma를 다시 호출하지 않으며, 명령을 다시 실행하면 Figma에서 변경된 내용만 다시 가져오고, 하나의 토큰으로 사용자의 Figma 계정이 볼 수 있는 모든 파일의 에셋, 브랜드 토큰, 컴포넌트에 사용할 수 있습니다.

• 4~5단계(모션/셰이더): 호환되는 Figma 커넥터가 필요하며, 토큰과는 별도의 인증이 필요합니다. 커넥터를 사용할 수 없거나 인증되지 않은 경우, 사용자에게 커넥터를 연결하거나 네이티브 내보내기를 제공하도록 요청한 후 중단하세요.
• 실패하는 단계에 정확히 어떤 자격 증명이 필요한지 알리세요 — 절대 분할 자체가 고장난 것처럼 표현하지 마십시오.
• BAD_TOKEN (401) 중간 발생 → 토큰이 만료되었거나 취소되었습니다. 다시 생성하세요. FORBIDDEN (403) → 메시지에 정확히 누락된 범위가 명시됩니다(예: 스타일 대체 경로의 경우 library_content:read) — 추가하세요. 그렇지 않으면 계정에서 파일을 볼 수 없습니다. REQUIRES_ENTERPRISE (변수에 대한 403) → 실패가 아닙니다: 스타일 대체 경로가 이미 실행되었습니다. RATE_LIMITED (429) → 클라이언트가 이미 백오프(backoff)와 함께 재시도했습니다(이는 모든 읽기 — 에셋, 토큰, 스타일, 노드 트리, 버전 — 에 적용됩니다. 재시도는 공유 요청 경로에 있으며 Retry-After를 준수하고 최대 60초로 제한됩니다). 계속 발생하면 1분 기다리거나 호출당 더 적은 노드를 가져오세요.

속도 제한 인식(명세 §2.1): 커넥터 할당량은 Figma 플랜에 따라 다릅니다 — 부모 프레임 요청을 일괄 처리하고, 요청하지 않는 한 검증 스크린샷을 건너뛰고, 원시 응답을 캐시하여 재파생이 두 번째 호출을 소모하지 않도록 하세요. REST는 분당 제한이 있습니다(분당 10+개, 엔드포인트별 버킷) — 대량 처리에 적합하며, 429 발생 시 백오프하세요.

라우팅

사용자의 Figma 링크를 parseFigmaRef(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/ 아래에 고정(freeze)하고, 출처와 함께 매니페스트를 추가하며, .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의 순수 도우미 함수에 전달하세요. 그렇지 않으면 네이티브 내보내기를 요청하세요:

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

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

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

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

가장 중요한 규칙: 스토리보드 프레임은 슬라이드가 아니라 키프레임입니다. 동일한 요소를 포함하는 두 프레임은 시간에 따른 해당 요소의 상태를 설명합니다 — 프레임을 일련의 스틸 이미지로 재생하지 말고 상태 간 요소를 애니메이션 처리하세요. 네 개의 연속된 프레임에 y가 감소하는 방식으로 그려진 로고는 4개의 키프레임을 통해 위로 올라가는 하나의 요소입니다. 스토리보드 프레임을 연속으로 재생하는 것은 실패 모드입니다. 이것이 암시하는 요소 타임라인을 재구성하는 것이 작업입니다.

스토리보드 파일은 기계적으로 구문 분석할 수 있는 문법을 따릅니다 — 눈으로 판단하지 말고 디코딩하세요:

1. 장면 단위: SECTION 내에서 프레임 크기의 모든 노드는 장면입니다 — 명명된 FRAME과 느슨한 전체 프레임 RECTANGLE(디자이너가 스틸을 섹션에 직접 붙여넣음) 모두 포함. 노드 유형이나 이름이 아닌 크기(≈ 컴포지션 종횡비, 예: >1400×900)로 필터링하세요.
2. 순서 = x-위치(스트립이 줄바꿈되면 행 우선). absoluteBoundingBox.x로 장면을 정렬하세요.
3. 인접 프레임을 diff하여 요소 체인 생성 — 이것이 애니메이션이 있는 곳입니다. 연속된 프레임 간에 자식을 일치시키세요: 먼저 이름(동일한 이름 = 동일한 요소 → 상태 간 상대 x/y/w/h 트윈)으로, 그다음 지오메트리 유사성(유사한 크기 + 근처 위치 + 유사한 채우기/획/효과 — 임계값: 면적 80% 유사 + 중심 오프셋 < 크기 50%)으로 일치시킵니다. 하위 요소가 새 프레임에 나타나지만 이전 프레임과 일치하지 않으면 fade-in입니다. 사라지면 fade-out입니다. 드리프트하지 않고 변환하면 모션입니다.
4. 불연속 상태를 트윈으로, 불연속 채우기를 전환으로 처리 — 요소가 위치에서 크기까지 모든 속성을 변경하면 하나의 GSAP 트윈(fromTo)입니다. 요소가 두 프레임 간에 유일하게 다른 점이 색상/불투명도이면 GSAP 전환입니다. 요소가 사라졌다가 다시 나타나면(중간 프레임에 없음) 두 개의 별도 동작: fade-out 및 fade-in입니다.
5. 요소 체인이 완성되면 motionContextToDocs(위 참조)에 직접 전달하세요 — 재구성된 MotionDoc을 사용하여 키프레임을 모션으로 구체화하세요. emitTimelineScript는 체인의 첫 번째 프레임을 기준으로 시간 0을 기준으로 정규화합니다.
6. npx hyperframes figma asset을 사용하여 각 장면의 1단계 스틸(충실도 검증용)을 동시에 가져온 후 원격 스토리보드 파일을 로컬에 고정된 에셋으로 대체하세요 — 그러면 모든 것이 연결된 참조이며 렌더링 시 Figma가 필요하지 않습니다.
7. 실행: npx hyperframes render --frames("---" 구분자로 결합된 각 장면) — 첫 번째와 마지막 프레임을 렌더링하여 정적 충실도를 검증하고, 시작과 끝을 확인하세요. 말이 된다면 전체를 렌더링하세요.

런타임 참고 사항

모든 통합은 HyperFrames의 결정론적 렌더링 계약을 존중합니다: 가져오기는 에셋과 메타데이터를 로컬에 고정하며, 렌더링 시 Figma를 다시 호출하지 않습니다. 각 명령은 명확한 입/출력 경계를 가지고 있어 AI 에이전트가 각 단계를 독립적으로 감사하고 재생할 수 있습니다. 에셋의 version 필드는 참조 무결성을 보장합니다 — fileKey:nodeId:format:scale이 동일하지만 version이 다른 두 번의 가져오기는 경쟁하지 않고 공존합니다.

문제 해결

• 403 (범위 누락) — 위의 인증 단계로 돌아가 누락된 범위를 정확히 추가하세요(예: 스타일 대체 경로의 경우 library_content:read). 필요한 범위는 파일 콘텐츠 읽기, 파일 메타데이터 읽기, 라이브러리 콘텐츠 읽기(게시된 스타일의 경우), 선택적으로 변수 읽기(변수의 경우)입니다.
• 401 (잘못된 토큰) — 만료/취소됨. figma.com/settings/security에서 새 토큰을 생성하고 shell/.env에서 FIGMA_TOKEN을 업데이트하세요.
• 429 (속도 제한) — 클라이언트가 이미 백오프와 함께 재시도했습니다. 1분 기다리거나 더 적은 노드를 일괄 처리하세요.
• 셰이더가 잘못 보임 — 커넥터를 통해 셰이더 픽셀을 캡처하지 마십시오. Figma에서 네이티브 내보내기를 요청하세요.
• 모션 불일치 — 검증 스크립트(verify-motion.mjs)를 실행하십시오. 15dB 미만이면 수동 번역 논리를 확인하십시오.

명확성과 유지보수성을 위해 각 명령을 실행하기 전에 항상 설명하세요.