HyperFrames 품질 게이트
개요
훌륭한 HyperFrames 실행과 평범한 실행의 차이는 창의성이 아니라 검증 훈련입니다. 훌륭한 실행은 모든 프레임을 픽셀이 여러 시점에서 확인될 때까지 증명되지 않은 것으로 취급합니다. 평범한 실행은 검사기를 신뢰하고 린트가 깔끔하게 통과된 첫 번째 결과물을 바로 출시합니다.
핵심 원칙: 린터는 사각형과 속성을 확인하지만, 렌더링된 픽셀만이 진실을 말합니다. 절대 프레임을 직접 보지 않고 완료되었다고 선언하지 마십시오.
필수 게이트
제작하거나 편집하는 모든 프레임에 대해 다음 순서로 작업하십시오. '작은 변경이니까'라는 이유로 게이트를 건너뛰는 것이 품질 저하의 원인입니다.
- 스토리보드 자체의
## Video direction블록을 읽고 사전 설정된 보일러플레이트보다 우선시하십시오. 스토리보드가 문장형 대문자를 요구하고 사전 설정의 frame.md가 모두 대문자일 때, 스토리보드가 우선합니다. 프로젝트 방향 > 사전 설정 기본값. - 프레임당 하나의 지배적 움직임. 하나의 프레임에 두 개의 요소가 동시에 해결되면 하나를 제거하십시오. 모든 것을 앞부분에 넣고 정지시키는('슬라이드쇼 모드') 방식과 모든 것이 떠다니는('화면 보호기 모드') 방식은 모두 실패입니다.
- 완료되었다고 말하기 전에 파일을 직접 grep하여 기계적 함정(아래 표)을 스스로 확인하십시오.
- 완료를 보고하기 전에 브라우저에서 seek-test를 수행하십시오.
<template>을 복제하고 타임라인을 등록한 다음timeline.seek(t, false)를 사용하여 t=0, 각 장면 경계 ±0.05초, 그리고 마지막 프레임에서 테스트하십시오. 각각 스크린샷을 찍으십시오. 직접 보십시오. seek-test 없이 프레임 보고서를 제출하는 것은 검증되지 않은 주장입니다.suppressEvents함정: 단순.seek(t)는onUpdate콜백을 억제합니다 — 카운터/타이핑이 하니스에서는 깨진 것처럼 보이지만 렌더러에서는 정상입니다. 항상false를 전달하십시오.
- 리타임 후에는 영향을 받은 클립의
data-start/data-duration을 다시 파생시키십시오. GSAP 트윈 시간과 클립 가시성 윈도우는 두 개의 별도 시스템입니다. 하나를 리타이밍하면서 다른 하나를 수정하지 않으면 보이지 않는 요소나 죽은 공기 간격이 발생합니다. 이것이 회귀의 #1 원인입니다. - 조립 후, 모든 컷 경계와 각 프레임의 중간 지점에서 전체 비디오를 스냅샷으로 찍고 직접 콘택트 시트 이미지를 읽으십시오. 잘못된 부분을 수정하고, 다시 스냅샷을 찍은 후에만 렌더링하십시오.
기계적 함정 표 (파일에서 grep으로 검색하십시오)
| 함정 | 증상 | 수정 방법 |
|---|---|---|
id가 숫자로 시작 + querySelector("#...") | SyntaxError로 타임라인 등록이 자동 실패 → 빈 프레임 | id 앞에 문자를 추가하거나, getElementById 사용 |
GSAP 애니메이션 요소에 CSS transform: 사용 | GSAP이 첫 번째 트윈에서 CSS 오프셋을 덮어씀 | 오프셋을 left/top에 고정; 변환은 GSAP에만 속함 |
패딩이 있는 카드에 box-sizing: border-box 누락 | 너비가 팽창, 중앙 정렬이 어긋남, 카드 충돌 | 모든 패딩이 있는 카드에 설정 |
@font-face가 fonts.gstatic.com / 모든 CDN을 가리킴 | 비결정적 렌더링, 오프라인에서 작동 불가 | assets/fonts/ 아래의 로컬 파일, 프로젝트 루트 기준 경로 사용 |
| 눈대중으로 겹침 계산 | 나중 카드가 이전 카드의 텍스트를 묻음 | 홀드 시간에 getBoundingClientRect()로 사각형 계산; 스크린샷에서 쌓인 모든 요소의 주요 텍스트가 보이는지 확인 |
| 클리핑/좁은 행간 텍스트에 대한 검사기 겹침 발견 | 잘못된 양성 (사각형은 겹치지만 글리프는 겹치지 않음) | 먼저 픽셀을 확인한 다음 data-layout-allow-overlap 사용 — 절대 맹목적으로 억제하지 마십시오 |
| 휴대폰 목업에서 스크린샷이 늘어나거나 색상이 변경됨 | 부자연스러운 기기 효과 | 항상 기본 종횡비 사용; overflow:hidden으로 자르고, 비균일하게 크기 조정 금지 |
외부 볼륨의 ._* AppleDouble 파일 | 빌드/렌더 실패 | 조립/렌더 전에 find . -name '._*' -delete 실행 |
| Node < 22 | CLI 실패 | export PATH="$HOME/.nvm/versions/node/v22*/bin:$PATH" (또는 nvm use 22) 접두사 사용 |
오케스트레이션 패턴 (다중 프레임 구축)
- 프레임당 하나의 워커, 워커당 하나의 파일; 워커는 절대 공유 파일에 접근하지 않습니다.
- 워커를 파견하기 전에 공유 자산(글꼴, 로고, 스크린샷)을 스테이징하십시오; 패킷은 정확한 경로를 명시합니다.
- 모든 패킷은 다음을 포함합니다: 프레임의 스토리보드 블록 그대로, 전역 Video direction 블록, 위의 함정 표, 그리고 seek-test 요구사항.
- 오케스트레이터는 워커가 보고한 내용과 관계없이 조립 후에 린트 + 검사 + 콘택트 시트 검사를 다시 실행합니다 — 워커의 자체 보고는 주장일 뿐 증거가 아닙니다.
위험 신호 — 멈추고 확인하십시오
- "린트와 검사가 통과했으니 프레임이 정확하다" → 검사는 묻힌 텍스트나 죽은 공기를 감지하지 못합니다. 픽셀을 확인하십시오.
- "트윈을 리타이밍했습니다. 완료입니다." → 클립의
data-*윈도우도 리타이밍했습니까? - "seek-test는 건너뛰겠습니다. 코드가 간단하니까요." → 빈 프레임 버그(숫자 ID 선택자)는 간단한 코드에서 발생했으며 seek-test만이 이를 발견했습니다.
- "카드가 다른 카드를 덮지 않을 것입니다." → 사각형을 계산한 다음 스크린샷을 찍으십시오.
- "CDN 글꼴은 이번 한 번만 괜찮습니다." → 그렇지 않습니다. 렌더는 네트워크 없이 수행되어야 합니다.
이 모든 것은: 건너뛰려고 했던 게이트를 실행하라는 의미입니다.