HyperFrames (코덱스 마케팅 스킬)

HyperFrames

HTML이 비디오의 진실 공급원입니다. Composition(구성)은 타이밍을 위한 data-* 속성, 애니메이션을 위한 GSAP 타임라인, 그리고 외형을 위한 CSS가 포함된 HTML 파일입니다. 이 프레임워크는 클립 가시성, 미디어 재생, 타임라인 동기화를 처리합니다.

접근법

HTML을 작성하기 전에, 높은 수준에서 생각하세요:

1. 무엇(What) — 시청자는 무엇을 경험해야 합니까? 내러티브 아크, 주요 순간, 감정적 포인트를 식별하세요.
2. 구조(Structure) — 몇 개의 Composition이 있고, 어떤 것이 하위 Composition이고 어떤 것이 인라인인지, 어떤 트랙이 무엇(비디오, 오디오, 오버레이, 자막)을 담당하는지.
3. 타이밍(Timing) — 어떤 클립이 지속 시간을 결정하는지, 전환이 어디에 위치하는지, 페이싱은 어떠한지.
4. 레이아웃(Layout) — 먼저 최종 상태를 구축하세요. 아래의 '레이아웃 후 애니메이션'을 참고하세요.
5. 애니메이션(Animate) — 그런 다음 아래 규칙을 사용하여 모션을 추가하세요.

작은 수정(색상 변경, 타이밍 조정, 한 요소 추가)의 경우, 바로 규칙으로 건너뛰세요.

시각적 아이덴티티 게이트

다음 순서로 확인하세요:

1. 프로젝트에 DESIGN.md가 존재합니까? → 읽으세요. 정확한 색상, 글꼴, 모션 규칙, 그리고 "하지 말아야 할 것" 제약을 사용하세요.
2. visual-style.md가 존재합니까? → 읽으세요. style_prompt_full 및 구조화된 필드를 적용하세요. (참고: visual-style.md는 프로젝트별 파일입니다. visual-styles.md는 8개의 명명된 프리셋이 있는 스타일 라이브러리로, 다른 파일입니다.)
3. 사용자가 스타일을 명명했습니까 (예: "스위스 펄스", "어둡고 기술적인", "럭셔리 브랜드")? → 8개의 명명된 프리셋을 위해 visual-styles.md를 읽으세요. 다음 항목이 포함된 최소한의 DESIGN.md를 생성하세요: ## Style Prompt (한 문단), ## Colors (3-5개의 역할이 있는 16진수 값), ## Typography (1-2개의 글꼴 패밀리), ## What NOT to Do (3-5개의 안티패턴).
4. 위에 해당하는 것이 없습니까? → HTML을 작성하기 전에 3가지 질문을 하세요:
   • 분위기는 어떤가요? (폭발적 / 영화적 / 유동적 / 기술적 / 혼란스러운 / 따뜻한)
   • 밝은 캔버스인가요, 어두운 캔버스인가요?
   • 특정 브랜드 색상, 글꼴 또는 시각적 참고 자료가 있나요? 그런 다음 답변을 바탕으로 최소한의 DESIGN.md를 생성하세요.

모든 Composition은 그 팔레트와 타이포그래피를 DESIGN.md, visual-style.md 또는 명시적인 사용자 지시 사항에 연결해야 합니다. 만약 #333, #3b82f6 또는 Roboto에 손이 간다면 — 이 단계를 건너뛴 것입니다.

모션 기본값, 크기 조정, 진입 패턴 및 이징에 대해서는 house-style.md를 따르세요. 하우스 스타일은 HOW(어떻게 움직일지)를 처리합니다. DESIGN.md는 WHAT(무엇처럼 보일지)을 처리합니다.

레이아웃 후 애니메이션

모든 요소를 가장 눈에 띄는 순간 — 완전히 진입하고, 올바르게 배치되었으며, 아직 나가지 않은 프레임 — 에 위치시켜야 합니다. 이를 먼저 정적인 HTML+CSS로 작성하세요. 아직 GSAP는 사용하지 마세요.

이것이 중요한 이유: 요소를 애니메이션 시작 상태(화면 밖, 0으로 축소, 투명도 0)에 배치하고 도달해야 한다고 생각하는 위치로 트윈하면, 최종 레이아웃을 추측하는 것입니다. 비디오가 렌더링될 때까지 겹침이 보이지 않습니다. 먼저 최종 상태를 구축하면, 모션을 추가하기 전에 레이아웃 문제를 확인하고 수정할 수 있습니다.

과정

1. 각 장면의 히어로 프레임을 식별하세요 — 가장 많은 요소가 동시에 보이는 순간입니다. 이것이 당신이 구축할 레이아웃입니다.
2. 해당 프레임에 대한 정적 CSS를 작성하세요. .scene-content 컨테이너는 width: 100%; height: 100%; padding: Npx;와 display: flex; flex-direction: column; gap: Npx; box-sizing: border-box를 사용하여 전체 장면을 채워야 합니다. 콘텐츠를 안쪽으로 밀어 넣기 위해 패딩을 사용하세요 — 콘텐츠 컨테이너에 position: absolute; top: Npx를 절대 사용하지 마세요. 절대 위치 콘텐츠 컨테이너는 콘텐츠가 남은 공간보다 높을 때 오버플로됩니다. position: absolute는 장식 요소에만 예약하세요.
3. gsap.from()을 사용하여 진입을 추가하세요 — 화면 밖/보이지 않는 곳에서 CSS 위치로 애니메이션합니다. CSS 위치가 진실 공급원이며, 트윈은 그곳에 도달하는 여정을 설명합니다.
4. gsap.to()를 사용하여 종료를 추가하세요 — CSS 위치에서 화면 밖/보이지 않는 곳으로 애니메이션합니다.

예시

/* scene-content가 장면을 채우고, 패딩이 콘텐츠를 배치합니다 */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* 컨테이너는 모든 장면 크기를 채웁니다 (1920x1080, 1080x1920 등).
   패딩이 콘텐츠를 배치합니다. Flex + gap이 간격을 처리합니다. */

잘못된 예 — 하드코딩된 치수와 절대 위치:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// 단계 3: 해당 위치로 애니메이션 진입
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// 단계 4: 해당 위치에서 애니메이션 종료
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

요소가 시간에 걸쳐 공간을 공유할 때

요소 A가 같은 영역에서 요소 B가 들어오기 전에 나간다면, 둘 다 각자의 히어로 프레임에 대해 올바른 CSS 위치를 가져야 합니다. 타임라인 순서는 시각적으로 공존하지 않음을 보장합니다 — 하지만 레이아웃 단계를 건너뛰면, 타이밍 오류로 인해 실수로 겹치는 경우를 잡지 못할 것입니다.

의도적인 겹침으로 간주되는 것

계층 효과(텍스트 뒤의 광선, 그림자 요소, 배경 패턴) 및 z-스택 디자인(카드 스택, 깊이 레이어)은 의도적입니다. 레이아웃 단계는 의도하지 않은 겹침 — 두 헤드라인이 서로 위에 겹쳐짐, 통계가 레이블을 덮음, 콘텐츠가 프레임 밖으로 흘러나감 — 을 잡기 위한 것입니다.

데이터 속성

모든 클립

속성	필수 여부	값
id	예	고유 식별자
data-start	예	초 단위 또는 클립 ID 참조 ("el-1", "intro + 2")
data-duration	img/div/composition에 대해 필수	초. 비디오/오디오는 기본적으로 미디어 지속 시간을 사용합니다.
data-track-index	예	정수. 같은 트랙의 클립은 겹칠 수 없습니다.
data-media-start	아니오	소스로부터의 트림 오프셋 (초)
data-volume	아니오	0-1 (기본값 1)

data-track-index는 시각적 레이어링에 영향을 주지 않습니다 — CSS z-index를 사용하세요.

Composition 클립

속성	필수 여부	값
data-composition-id	예	고유 Composition ID
data-start	예	시작 시간 (루트 Composition: "0" 사용)
data-duration	예	GSAP 타임라인 지속 시간보다 우선함
data-width / data-height	예	픽셀 치수 (1920x1080 또는 1080x1920)
data-composition-src	아니오	외부 HTML 파일 경로

Composition 구조

data-composition-src를 통해 로드된 하위 Composition은 <template> 래퍼를 사용합니다. 독립형 Composition (메인 index.html)은 <template>를 사용하지 않습니다 — data-composition-id div를 직접 <body>에 넣습니다. 독립형 파일에 <template>를 사용하면 모든 콘텐츠가 브라우저에서 숨겨져 렌더링이 깨집니다.

하위 Composition 구조:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- 콘텐츠 -->
    <style>
      [data-composition-id="my-comp"] {
        /* 범위 지정 스타일 */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // 트윈...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

루트에서 로드: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

비디오 및 오디오

비디오는 반드시 muted playsinline이어야 합니다. 오디오는 항상 별도의 <audio> 요소입니다:

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

타임라인 계약

• 모든 타임라인은 { paused: true }로 시작합니다 — 플레이어가 재생을 제어합니다.
• 모든 타임라인을 등록하세요: window.__timelines["<composition-id>"] = tl
• 프레임워크가 하위 타임라인을 자동으로 중첩합니다 — 수동으로 추가하지 마세요.
• 지속 시간은 GSAP 타임라인 길이가 아닌 data-duration에서 비롯됩니다.
• 지속 시간을 설정하기 위해 빈 트윈을 절대 만들지 마세요.

규칙 (절대적)

결정론적 (Deterministic): Math.random(), Date.now() 또는 시간 기반 로직을 사용하지 마세요. 의사 난수 값이 필요하면 시드 기반 PRNG(예: mulberry32)를 사용하세요.

GSAP: 시각적 속성(opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, 변환)만 애니메이션하세요. visibility, display를 애니메이션하거나 video.play()/audio.play()를 호출하지 마세요.

애니메이션 충돌: 동일한 요소의 동일한 속성을 여러 타임라인에서 동시에 애니메이션하지 마세요.

repeat: -1 금지: 무한 반복 타임라인은 캡처 엔진을 망가뜨립니다. Composition 지속 시간에서 정확한 반복 횟수를 계산하세요: repeat: Math.ceil(duration / cycleDuration) - 1

동기식 타임라인 구축: async/await, setTimeout 또는 Promise 내에서 타임라인을 절대 구축하지 마세요. 캡처 엔진은 페이지 로드 후 window.__timelines를 동기적으로 읽습니다. 폰트는 컴파일러에 의해 포함되므로 즉시 사용 가능합니다 — 폰트 로딩을 기다릴 필요가 없습니다.

절대 하지 말아야 할 것:

1. window.__timelines 등록을 잊지 마세요.
2. 오디오 대용으로 비디오를 사용하지 마세요 — 항상 음소거된 비디오 + 별도의 <audio>를 사용하세요.
3. 비디오를 시간이 지정된 div 안에 중첩하지 마세요 — 시간이 지정되지 않은 래퍼를 사용하세요.
4. data-layer (대신 data-track-index 사용) 또는 data-end (대신 data-duration 사용)를 사용하지 마세요.
5. 비디오 요소 치수를 애니메이션하지 마세요 — 래퍼 div를 애니메이션하세요.
6. 미디어에서 play/pause/seek을 호출하지 마세요 — 프레임워크가 재생을 소유합니다.
7. data-composition-id 없이 최상위 컨테이너를 만들지 마세요.
8. 어떤 타임라인이나 트윈에서도 repeat: -1을 사용하지 마세요 — 항상 유한한 반복을 사용하세요.
9. 타임라인을 비동기적으로 구축하지 마세요 (async, setTimeout, Promise 내부).
10. 이후 장면의 클립 요소에 gsap.set()을 사용하지 마세요 — 페이지 로드 시 DOM에 존재하지 않습니다. 대신 타임라인 내에서 클립의 data-start 시간 이상에서 tl.set(selector, vars, timePosition)을 사용하세요.
11. 콘텐츠 텍스트에 <br>을 사용하지 마세요 — 강제 줄바꿈은 피하세요.