Communitygithub.com

Figma → HyperFrames

Figma 콘텐츠를 HyperFrames 컴포지션으로 가져옵니다. 렌더링된 에셋, 브랜드 토큰, 컴포넌트, 스토리보드 섹션을 포함하며, 프레임을 슬라이드가 아닌 상태로 읽어 모션을 재구성합니다. (REST/CLI), 커넥터 기반 모션(사용 가능 시), 그리고 커넥터 또는 네이티브 익스포트의 셰이더를 지원합니다. 사용자가 figma.com 링크를 붙여넣거나 Figma 디자인, 프레임, 로고, 브랜드, 애니메이션을 비디오/컴포지션으로 가져오라고 요청할 때 사용합니다.

Figma → HyperFrames란 무엇인가요?

이 스킬은 Figma 디자인 데이터를 HyperFrames 컴포지션 시스템으로 가져오기 위한 포괄적인 파이프라인을 제공합니다. CLI 및 선택적 Figma 커넥터를 통해 정적 에셋(Phase 1), 브랜드 토큰 및 스타일(Phase 2), 편집 가능한 HTML 컴포넌트(Phase 3), 모션/애니메이션 데이터(Phase 4), 셰이더(Phase 5)를 가져옵니다. REST API를 사용하여 에셋과 토큰을 가져오고, 로컬에 동결시켜 결정론적 렌더링을 보장하며, `FIGMA_TOKEN` 환경 변수로 인증합니다. 모션(Phase 4)과 셰이더(Phase 5)는 REST 지원이 없으므로 Figma 커넥터나 네이티브 익스포트가 필요하다고 명시합니다. 스토리보드는 '프레임 = 키프레임' 접근 방식을 사용하여, 여러 프레임에 걸친 요소 상태 변화를 애니메이션으로 전환하며, GSAP과 같은 라이브러리를 활용해 부드러운 모션을 만듭니다. 이 스킬은 현재 'Retired' 상태의 HTML/GSAP 파이프라인을 설명하며, 향후 Remotion(React) 기반의 `/hyperframes-core`로 포팅될 예정입니다. 사용자는 이전 파이프라인의 데이터 마크업이나 GSAP 코드를 복사하지 말고, 디자인 의사 결정(스토리 구조, 컷 리듬 등)만 참고해야 합니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/MattiaIppoliti/tia-skills/tree/HEAD/skills/video/figma

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

⚠ 계약 상태: 아직 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정적 에셋RESThyperframes figma asset
2브랜드 토큰/스타일RESThyperframes figma tokens
3컴포넌트 → HTMLRESThyperframes figma component
4모션 → GSAP커넥터 사용 가능 시모션 컨텍스트 사용
5셰이더커넥터 / 수동 익스포트사용 또는 네이티브 익스포트

REST는 가능한 모든 곳에서 사용됩니다 (대량 사용 가능, 헤드리스). 호환되는 Figma 커넥터는 모션 및 셰이더 데이터에 선택 사항입니다. 커넥터가 없으면 네이티브 익스포트를 요청하세요. 모든 경로는 에셋을 로컬에 동결시켜 렌더가 결정론적으로 유지되도록 합니다. 스토리보드 재구성은 Phase-1 에셋 익스포트(REST)를 에이전트 주도 타임라인 어셈블리와 결합합니다 — 커넥터가 필요하지 않습니다. 기존 동결 에셋, 매니페스트 레코드 및 바인딩은 라우팅 변경의 영향을 받지 않습니다 — 분할은 다음 가져오기가 사용하는 자격 증명만 변경합니다.

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

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

  1. figma.com/settings → 보안 → Personal access tokens → 새 토큰 생성.
  2. 범위 — 읽기 전용은 이 통합에 필요한 전부입니다 (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 준수).
  3. 사용자가 셸 프로필이나 프로젝트 .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의 순수 헬퍼에 전달하세요; 그렇지 않으면 네이티브 익스포트를 요청하세요:

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

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

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

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

핵심 규칙: 스토리보드 프레임은 키프레임이지 슬라이드가 아닙니다. 동일한 요소를 포함하는 두 프레임은 시간에 따른 해당 요소의 상태를 설명합니다 — 상태 간에 ELEMENT를 애니메이션화하세요. (이하 생략)

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

MattiaIppoliti/tia-skills

The technique catalog: five velocity-matched SEAMS (zoom-through, INVERSE zoom-through, cut-the-curve, waterfall cut, rack-focus blur-cut) plus the two in-scene techniques — waterfall ENTRY (staggered arrival cascades for title cards / segment openers) and the nudge curve (slow-fast-slow three-phase group slides). Covers partial-travel (~12% of frame) velocity matching via mirrored power4 eases, the Z scale-sign rule, size-scaled blur (10px text / 18-20px full-frame), word-by-word staggered cuts, cascade pacing by element weight, and the 10/65/25 slide ratio. Read before authoring any transition, text-beat handoff, kinetic text entry, or group reposition. [depth, zoom, inverse-zoom, scale-sign, mirrored-zoom, rack-focus, pacing, velocity, cut-the-curve, waterfall, stagger, cascade, kinetic-text, title-card, segment-opener, nudge, slide, easing, group-motion, z-depth, motion-graphics, cinematic, transition, blur, directional-continuity]

MattiaIppoliti/tia-skills

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

MattiaIppoliti/tia-skills

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

MattiaIppoliti/tia-skills

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

MattiaIppoliti/tia-skills

Drive the Remotion CLI development loop: scaffold, studio, type-check, compositions, still probes, single and batch render, bundle, Lambda and Cloud Run rendering, benchmark, versions, upgrade, and GPU checks. Also use when diagnosing a build or render failure, or when looking for a capability the retired HyperFrames CLI used to own.

MattiaIppoliti/tia-skills

The composition contract for building one renderable Remotion project. Use for project structure, `<Composition>` registration, `<Sequence>` timing, layer/track ordering, scene components, props and schemas, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition code.

관련 스킬