Communitygithub.com

1999AZZAR/designer-mcp

HyperFrames 합성 계약 — 하나의 렌더링 가능한 프로젝트를 구축합니다. 합성 구조, `data-*` 타이밍 속성, `class="clip"`, 트랙, 서브 합성, 변수, 프레임워크 소유 미디어 재생, 결정론적 렌더링 규칙 및 검증에 사용합니다. 합성 HTML을 작성하기 전에 읽으십시오.

designer-mcp란 무엇인가요?

이 스킬은 HyperFrames 프레임워크의 핵심 기술 계약을 정의합니다. HyperFrames는 HTML 파일을 입력으로 받아 DOM 요소의 `data-*` 속성을 통해 타이밍을 선언하고, GSAP과 같은 애니메이션 런타임을 제어하여 동영상을 렌더링합니다. 개발자는 이 가이드를 통해 합성(composition) 구조, 서브 합성(sub-composition) 연결, CSS와 GSAP 간 충돌 방지, 렌더링 결정론 보장 등 프레임워크 사용의 핵심 규칙을 이해할 수 있습니다. Claude Code, Cursor, Codex와 같은 AI 코딩 에이전트가 HyperFrames 프로젝트를 정확하게 생성 및 편집하고, 검증 도구(`npx hyperframes check`)로 품질을 확인하며, 최종 렌더링을 수행할 수 있도록 돕습니다. 본 스킬은 `references/` 디렉토리의 세부 문서와 `hyperframes-animation`, `hyperframes-cli` 등 다른 도메인 스킬과 함께 사용되어야 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1999AZZAR/designer-mcp/tree/HEAD/skills/video/engine/hyperframes-core

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

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

문서

HyperFrames Core

Agent 함정 (먼저 읽기):

  • flex/inset으로 중앙 정렬하고, GSAP x/y로 트윈할 노드에 CSS transform: translate(-50%,-50%)를 사용하지 마십시오. 린트: gsap_css_transform_conflict. fromTo 또는 xPercent/yPercent를 사용하십시오.
  • 장면 종료 tl.set(..., {visibility:"hidden"})를 추가하지 마십시오. 런타임이 이미 타이밍된 클립을 숨깁니다. 내부 노드(또는 .clip의 opacity)에 대한 페이드 아웃이면 충분합니다. 자막 하드 킬은 다른 규칙입니다.
  • window.__timelines["id"]는 루트 data-composition-id와 일치해야 합니다.
  • render 후, 요약의 두 번째 줄(beginframe vs screenshot, GPU 모드, 단계 타이밍)을 읽으십시오. Linux에서 screenshot + software gpu는 느린 경로입니다.

HyperFrames는 HTML에서 비디오를 렌더링합니다. 합성(composition)이란 DOM이 data-* 속성으로 타이밍을 선언하고, 애니메이션 런타임이 seek 가능하며, 미디어 재생이 프레임워크에 의해 소유되는 HTML 파일입니다.

이 스킬은 기술 계약입니다 — 하나의 hyperframes 프로젝트를 구축하는 방법입니다. 아래 본문은 빌드 가이드입니다. 주제별 세부 사항은 references/(다음 색인 참조)에 있으며, 필요 시 읽으십시오. 프로세스 문서(브리핑, 스토리보드, 검토, 프로덕션, 디스패치, 프레임-워커)는 /hyperframes → references/에 있습니다. 다른 사항은 형제 도메인 스킬(hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry)에 있습니다. /hyperframes의 기능 맵은 각 스킬이 다루는 내용을 설명합니다.

참고 자료

파일읽는 목적
references/minimal-composition.md가장 작은 렌더링 가능한 합성 스켈레톤에서 시작
references/composition-patterns.md모놀리식 vs 모듈식 선택; 모듈식 index.html 구조화; 서브 컴프 아키타입 선택
references/data-attributes.mddata-* 속성(루트 / 클립 / 서브 컴프 호스트 / 레거시 별칭) 조회; class="clip" 사용
references/tracks-and-clips.mddata-track-index가 제어하는 것(과 제어하지 않는 것), z-index, 다른 클립 기준 타이밍 이해; npx hyperframes timeline으로 모든 트랙과 클립 나열
references/creator-editing-recipes.md컷/트림/재정렬/시간 재설정/프리즈/카메라/마스크/크로스페이드/오디오 편집 레시피와 그 제한 사항을 정확히 복사
references/sub-compositions.md서브 합성 연결(호스트 속성, <template>, 인스턴스별 변수) 및 내부 애니메이션
references/variables-and-media.md변수 선언; <video>/<audio> 배치, 볼륨 설정, 트림
references/determinism-rules.mdseek 가능한 타임라인 구축; 결정론 금지 사항; 레이아웃 / 텍스트 맞춤
references/full-screen-motion.md공유 배경을 사용한 전체 프레임 모션 작성
references/tailwind.mdTailwind v4 프로젝트에서 작업 (init --tailwind; 런타임 계약은 Studio의 v3와 다름)

애니메이션 런타임 세부 사항(GSAP API, Lottie, Three.js 등)은 hyperframes-animation → adapters/<runtime>.md를 참조하십시오.

합성 구축

두 가지 루트 형태 (상호 교환 불가)

  • 독립형 (최상위 index.html): 루트 <div data-composition-id="…">가 <body>에 직접 위치하며, <template> 래퍼가 없습니다. 독립형 루트를 래핑하면 모든 콘텐츠가 숨겨지고 lint에서 거부됩니다(standalone_composition_wrapped_in_template, 오류).
  • 서브 합성 (data-composition-src를 통해 로드): 루트를 <template>으로 감쌉니다. 이 형태가 작성할 모양입니다. 로더는 일반 전체 문서도 허용하고 <body>로 폴백하지만, 템플릿 형태가 예제와 도구에서 가정하는 형태입니다.

⚠ 전송 규칙: 템플릿화된 서브 합성의 경우 어셈블러는 파일 자체의 <head> <style>/<script>를 삭제합니다(packages/core/src/compiler/compositionAssembly.ts, hasTemplate 게이트). 따라서 <style>/<script>를 템플릿 내부에 넣으십시오. <link>는 어느 쪽이든 호이스트됩니다. ⚠ 호스트 ID 규칙: 호스트 슬롯, 내부 템플릿, window.__timelines["<id>"] 키에 동일한 ID를 부여하십시오. 다른 로컬 ID도 지원되지만(어셈블러는 파일의 첫 번째 루트로 폴백), 불일치는 조용히 발생하므로 특별한 이유가 없다면 일치시키십시오.

파일 형태, 호스트 연결, 사전 렌더링 체크리스트 → references/sub-compositions.md

루트는 크기가 지정되어야 함 (무음 레이아웃 버그)

독립형 루트는 width/height: 100%를 작성합니다. 캔버스 크기는 data-width/data-height입니다. 런타임이 해당 픽셀을 합성 루트에 스탬프합니다. #root에 1920px/1080px을 하드코딩하지 마십시오. 스켈레톤 → references/minimal-composition.md

하나의 일시 중지된 타임라인

각 합성은 window.__timelines["<id>"](키 = 루트 data-composition-id)에 정확히 하나의 gsap.timeline({ paused: true })를 등록합니다. 비동기 콜백(document.fonts.ready) 내부에서 구축하는 것도 지원됩니다. 중요한 것은 빌드가 완료된 후에만 등록해야 한다는 것입니다. 렌더링 길이는 루트의 data-duration이며, 타임라인의 길이가 아닙니다: 타임라인이 이를 초과하면 잘리고, 일찍 끝나면 마지막 프레임을 유지합니다. 루트 data-duration을 생략하면 길이가 대신 추론됩니다(타임라인, 미디어 윈도우 또는 어댑터). window.__timelines = window.__timelines || {}가 필요하지 않습니다. 런타임이 인라인 스크립트가 실행되기 전에 레지스트리를 생성하며, lint가 더 이상 요청하지 않습니다. 하위 타임라인을 호스트에 수동으로 중첩시키지 마십시오. 런타임이 등록된 하위 타임라인을 자동으로 중첩시킵니다. 전체 계약(GSAP 이외의 런타임 포함) → references/determinism-rules.md + hyperframes-animation/adapters/

첫 번째 패스 린트 주의 사항 (첫 빌드 실패 보장)

lint가 잡아내는 규칙이지만, 사후에만 잡습니다. 처음부터 올바르게 작성하십시오:

  • CSS 초기 transform과 동일한 속성에 대한 GSAP 트윈을 절대 쌍으로 사용하지 마십시오. CSS 값과 트윈의 시작이 충돌하며 lint가 gsap_css_transform_conflict로 거부합니다. CSS transform: translateX(-40px) 대신 gsap.fromTo(el, { x: -40 }, { x: 0 })로 트윈 내부에 초기 상태를 설정하십시오.
  • <video>/<audio>에 crossorigin을 절대 넣지 마십시오. lint가 캔버스/WebGL/WebAudio 읽기백을 포함하여 무조건 media_crossorigin_breaks_preview(오류)로 거부합니다. 억제가 불가능합니다.
  • data-start가 있는 <video>의 조상 요소에 data-start를 절대 부여하지 마십시오. lint가 video_nested_in_timed_element(오류)로 거부합니다. 래퍼 또는 비디오 중 하나에만 타이밍을 지정하고, 둘 다에 하지 마십시오.
  • 모든 <audio>에는 id가 필요합니다. lint가 media_missing_id로 거부하며, ID가 없는 <audio>는 믹서에 의해 절대 선택되지 않으므로 렌더링이 무음이 됩니다.
  • .clip을 autoAlpha 또는 visibility로 트윈하지 마십시오. lint가 gsap_animates_clip_element로 거부합니다. 대신 자식을 애니메이션하십시오.
  • 명명된 CSS font-family는 제공된 로컬 파일에 대한 파일 내 @font-face가 필요합니다. 그렇지 않으면 lint가 font_family_without_font_face를 발생시킵니다.
  • 서브 합성 #root는 하드코딩된 1920px/1080px이 아닌 width/height: 100%(또는 inset: 0)를 사용합니다. 캔버스 크기는 data-width/data-height입니다.

린트 오류는 레이아웃 및 대비 감사도 비활성화합니다. check는 0 sample(s) 및 0/0 text checks를 보고하는데, 이는 깨끗한 파일처럼 읽히지만 아무것도 실행되지 않았음을 의미합니다. 이러한 숫자를 신뢰하기 전에 린트 오류를 먼저 해결하십시오.

양보할 수 없는 규칙 (자동 게이트가 놓칠 수 있는 무음 버그)

여기에 표시됩니다. 전체 근거는 연결된 참조에 있습니다. 위반하지 마십시오:

  • 렌더링 시간 시계 / 시드되지 않은 Math.random / 네트워크 / 입력 상태 없음; repeat: -1 없음(유한 횟수 사용). → determinism-rules.md
  • .clip 요소에서 display, visibility 또는 autoAlpha를 절대 트윈하지 마십시오. 프레임워크가 클립 가시성을 소유하며, lint가 거부합니다(gsap_animates_clip_element). 대신 자식을 애니메이션하십시오. → determinism-rules.md
  • 본문 텍스트에 <br> 없음; 변환된 요소는 블록 수준 + 크기 지정되어야 함; 펄스 절대 장식 요소는 피크 여유 공간이 필요함. → determinism-rules.md
  • <video>/<audio>는 평면 문서 쿼리로 찾아지므로, 프레임워크가 모든 중첩 깊이(서브 컴프 <template> 또는 래퍼 내부 포함)에서 seek 및 디코딩합니다. 하나의 하드 제한: data-start가 있는 <video>가 data-start도 함께 있는 다른 일반 요소 내부에 있으면 lint가 오류를 발생시키며, 실패는 실제입니다(잘못된 소스 프레임, 클립이 슬롯 중간에 사라짐). 따라서 래퍼나 비디오 중 하나에만 타이밍을 지정하고 둘 다에 하지 마십시오. 서브 합성 호스트는 예외입니다. 서브 합성 내부의 미디어는 올바르게 렌더링됩니다. 다른 주의 사항은 타임라인, 배치가 아닙니다. 서브 컴프 타임라인은 호스트 루트 요소를 애니메이션할 수 없습니다. → variables-and-media.md
  • 조립된 페이지 전체에서 모든 id를 고유하게 유지하십시오(서브 컴프 id에 컴포지션 id 접두사 #<id>-hero를 붙임) 자체 #id CSS 및 getElementById 호출이 해결되도록 합니다. 프레임 주입은 더 이상 이에 의존하지 않습니다. 컴파일러는 모든 video[src]/audio[src]/img[src]에 문서 고유 data-hf-render-id를 스탬프합니다. src 속성 대신 <source> 자식을 사용하는 미디어는 스탬프되지 않으므로 고유 ID가 여전히 중요합니다. → composition-patterns.md
  • 일반 렌더링에서 합성 루트의 전체 화면 채우기는 괜찮습니다. 레이어드 복합 경로(HDR 콘텐츠 또는 셰이더 전환을 사용하는 합성)에서만 삭제됩니다. 이 경로에서는 엔진이 모든 합성 루트를 투명하게 강제하여 아래 레이어가 비쳐 보이도록 합니다. 합성이 셰이더 전환이나 HDR 미디어를 사용하는 경우, 채우기를 전체 블리드 자식(position:absolute; inset:0)에 넣으십시오. → composition-patterns.md

기존 합성 편집

  • 먼저 파일을 읽으십시오. 관련 없는 타이밍, 트랙, ID, 변수, 미디어 경로는 유지하십시오.
  • 프로젝트 타임라인(트랙, 클립, 시작, 끝, 재생 내용)을 확인하려면 index.html과 모든 서브 합성 파일을 읽는 대신 npx hyperframes timeline [--json]을 실행하십시오.
  • 기존 합성 ID 및 타임라인 키와 일치시키십시오.
  • 클립 추가: 주변 클립과 의도적으로 data-start/data-duration을 설정하십시오. data-track-index는 Studio 디스플레이 레인이며 타이밍 제약이 아니므로 비어 있을 필요가 없습니다.
  • 합성 요소의 data-hidden은 미리보기와 렌더링 모두에서 요소를 숨겨 시간 윈도우를 재정의합니다. 비파괴적/되돌릴 수 있으며 Studio 타임라인의 눈 아이콘으로 전환됩니다.
  • 서브 합성 추가: 호스트를 연결하기 전에 내부 data-composition-id를 확인하십시오.

검증

명령어 세부 사항은 hyperframes-cli 사용

  • npx hyperframes check 통과(린트, 런타임, 레이아웃, 모션, 대비에서 0개의 발견 사항)
  • 서브 합성이 있는 프로젝트: npx hyperframes snapshot --at <중간점> 각 프레임을 눈으로 확인
  • npx hyperframes preview --background 검토용(사용자는 Studio 타임라인에서 무엇이든 편집할 수 있으며 서버는 호출 명령 이후에도 유지됨)
  • 사용자 승인 후에만 npx hyperframes render

Individual skills in this repo

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

1999AZZAR/designer-mcp

SOTA animation and physics heuristic guide using motion.dev

1999AZZAR/designer-mcp

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

1999AZZAR/designer-mcp

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). 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`.

1999AZZAR/designer-mcp

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

1999AZZAR/designer-mcp

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1999AZZAR/designer-mcp

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

1999AZZAR/designer-mcp

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1999AZZAR/designer-mcp

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

1999AZZAR/designer-mcp

Use when building or editing a HyperFrames project that people open in Studio: how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

1999AZZAR/designer-mcp

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

1999AZZAR/designer-mcp

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

1999AZZAR/designer-mcp

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

1999AZZAR/designer-mcp

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.

관련 스킬