UI 데모 구성기
여기서 제품 비디오는 비디오당 작성하는 세 개의 파일과 모든 비디오가 공유하는 키트로 구성된 하나의 HyperFrames 컴포지션입니다:
| 파일 | 설명 | 편집자 |
|---|---|---|
video/build.py | 비트 테이블 T: 모든 시간이 단어 타이밍에서 파생됨 | 사용자 |
video/src/template.tpl | 재구성된 UI, 화면 레이어 및 GSAP 타임라인 | 사용자 |
video/src/app.css | 제품 UI CSS, specs/의 리터럴 값 | 사용자 |
kit/stage.css, kit/titles.css, kit/stage.js | 스테이지 레이어 및 seek-safe 헬퍼 | 이 기술 |
products/<slug>/kit/tokens.css, fonts/, icons/, ui/ | 제품의 토큰, 폰트, 아이콘 및 공유 UI 조각 | product-kit |
video/index.html | build.py에 의해 생성됨. 수동으로 편집하지 마세요 | 없음 |
scripts/buildlib.py는 모든 빌드의 일반적인 부분(타이밍, 서명 게이트, 오디오 태그, 인라인, 플레이스홀더, 아이콘, 카메라 클램프)을 처리하여 build.py가 간결한 비트 목록을 유지하도록 합니다.
스테이지 모델
#root > #stage > #camera > #blurWrap > #app 제품, 앱 픽셀 단위
> #veil, .pvs-ttl, #endS, #lock, #fade 화면 공간, 1920x1080
- UI는 실제 뷰포트에서 재구성되어 한 번 스케일링됩니다.
#app은product.yaml app_canvas.logicalCSS 픽셀(예: 1440x810)이며, 하나의 변환으로 1920x1080으로 스케일링됩니다. 프로덕션 CSS는 리터럴 픽셀을 유지하므로 사양 값이 변경 없이 붙여넣어지고 모든 측정값이 코드와 1:1로 비교됩니다. 앱의 중단점 위에 있는 데스크톱 너비를 16:9로 선택하세요. 화면 녹화가 있는 경우 해당 논리적 크기를 사용하세요. 16:9가 아닌 캔버스는 레터박스 처리됩니다(buildlib이 경고함). - 위치는 측정되며, 입력되지 않습니다.
S.box(sel)은 폰트 로드 후#app까지의 오프셋을 합산합니다. CSS가 변경되어도 커서는 여전히 버튼 위에 위치합니다. - 커서와 클릭 리플은
#app의 마지막 자식 요소이므로 제품과 함께 스케일 및 블러 처리됩니다. 팝업(.pvs-modal) 및 토스트(.pvs-toast-slot)도#app내에 있습니다. #camera만 움직이고#blurWrap만 블러 처리됩니다.#app또는#stage를 트윈(tween)하지 마세요.
프레이밍: 기본값 1x 전체 페이지
기본적으로 모든 제품 비트를 1x, 전체 페이지로 설정하고, 팝업은 자연스러운 크기로 앱이 표시하는 방식대로 중앙에 배치합니다. 푸시인은 부드럽게(video.max_zoom까지, 기본값 1.35), 전체 섹션을 프레임 내에 유지하고 프레임 가장자리가 레이블을 통과하지 않도록 합니다. 챕터당 하나의 프레이밍: 제품이 초점에서 벗어난 상태에서 챕터 제목 뒤에서 이동하거나, 하나의 느린 시그니처 동작으로 수행합니다.
이유: 이 기술이 비롯된 프로덕션에서 설정 비디오가 줌으로 인해 두 번 거부되었습니다.
1.67x 펀치인은 레이블을 반으로 잘랐고("무슨 일이 일어나고 있는지 알 수 없음"), 나중에 컬럼당 약 2x의 프레이밍은
아무것도 잘리지 않았음에도 비좁게 느껴졌습니다. 검토자가 모범으로 제시한 비디오는 항상 1x로 실행되었습니다.
멀리 떨어진 캔버스(50%로 표시) 또는 좁은 채팅 컬럼은 더 많은 것을 허용합니다:
해당 제품에 대해 product.yaml에서 max_zoom을 높이고, 비트별로는 높이지 마세요.
b.cam() 및 S.cam()은 max_zoom 이상에서 클램프하고 경고합니다. 세부 사항 및 숫자:
references/framing-and-pacing.md.
페이싱: 챕터는 일시 정지
- UI 중간이 아닌 컨텍스트에서 열기: 로고, 제품 이름 및 제품에 대한 한 줄 설명, 초점이 흐려진 제품 위에.
- 각 챕터는 초점이 흐려진(블러 + 베일) 제품 위에 투톤 제목으로 열리고, 최소 약 1.4초 동안 유지되며, 첫 번째 동작을 명명하는 단어 직전에 초점이 돌아옵니다. 화면 변경은 제목 뒤에서 발생하므로 하드 컷이 없습니다.
- 챕터당 하나의 아이디어, 한 번에 하나의 변경, 0.6
1초 간격, 각 챕터 끝에 약 0.8초의 유지. 제품의 실제 대기 시간은 12초로 압축됩니다. - 엔드 화면은 범위(제품이 수행하는 다른 작업, 실제 UI 조각 사용)를 보여준 후 록업을 보여줍니다.
이유: 0.5초마다 미세 동작이 있는 밀집된 원테이크 컷은 제작자에게는 세련미로 읽히고 검토자에게는 노이즈로 읽혔습니다("너무 빠르고, 한 번에 너무 많고, 압도적임") 결과를 확대 및 축소하여 따라가기 불가능하게 만들었습니다. 차분한 챕터 버전이 승인되었습니다.
모든 비트는 단어에 고정됩니다
b = buildlib.Build(__file__)
T, w, end = b.T, b.w, b.end
T["N2"] = T["ch1"] + 0.3 # 클립 ID 배치는 해당 클립을 배치합니다
T["rack1"] = T["N2"] + w("N2", "after") - 0.25 # "after" 직전에 초점이 돌아옴
T["send1"] = max(T["type1"] + T["type1Dur"] + 0.4, end("N3") + 0.15)
w(clip, prefix, nth=1)은 클립을 기준으로prefix로 시작하는 첫 번째 단어의 시작입니다. 단어가 없으면 예외를 발생시킵니다(자동 대체 없음: 조용히 기본 시간에 비트를 배치하는 대체는 모션이 음성에서 눈에 띄지 않게 멀어지게 하는 방법입니다).- UI 이벤트는 이를 명명하는 단어보다 0.05~0.45초 먼저 발생합니다.
max()는 내레이션 순서와 "UI가 완료됨"을 모두 유지합니다.end(k)는T[k]에 클립 지속 시간을 더한 값입니다(또는b.dur(k, d)). - 타이핑 속도는 초당 문자 수(약 17~21)이거나 비트에 맞게 고정됩니다.
- 클릭, 타이핑 및 팝업은 동일한
T에서 사운드를 가져오므로(b.click(t),b.typing(text, t, dur),b.pop(t)), 리타이밍된 비트는 사운드도 이동시킵니다. - 음성의 한 줄을 재생성하면 전체 비디오의 타이밍이 다시 계산됩니다. 그것이 요점입니다.
이유: 타이밍에는 하나의 진실 공급원이 있습니다. 라인이 재생성되면 여기에 고정된 모든 것이 함께 이동합니다. 수동으로 입력한 초는 첫 번째 재촬영에서 쓸모없게 됩니다.
워크플로우
BRIEF.md(챕터, 프레이밍),COVERAGE.md(각 챕터가 화면에서 설명해야 하는 것),specs/*.md및TRUTH.md를 읽습니다. UI를 발명하지 마세요:SOURCES.md또는specs/에 출처가 없는 화면이나 동작은 제외합니다.- 사양에서
src/template.tpl및src/app.css의 화면을 재구성하고, product.yamlcast의 가상 데이터를 사용합니다. 다른 비디오에서 복사하는 대신kit/ui/의 제품 조각을{{UI:name}}으로 재사용합니다 (references/ui-component-library.md). build.py에 비트를 작성하고 키트 헬퍼를 사용하여 템플릿에 타임라인을 작성합니다 (references/stage-kit.mdAPI 참조,references/beat-recipes.md각 비트 참조,references/end-screen-and-lockup.md). 모든 트윈에 대해 seek-safe-motion 기술을 따릅니다.- 드래프트를 빌드하고 인쇄되는 비트 테이블을 읽습니다:
음성이 생성되기 전에PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)" "$PVS_HOME/bin/pvs-py" <video_dir>/video/build.py --draft--draft --fake-timings는lines.tsv에서 단어 타이밍을 생성하여 화면을 배치할 수 있도록 합니다. <video_dir>/video/에서 린트 및 검사:오류 0개 및 런타임 경고 0개를 예상합니다. 하나의 린트 경고는 모놀리식 스테이지에 대해 예상됩니다:"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" . npx --yes [email protected] checkcomposition_file_too_large(키트가 인라인됨). 그런 다음 빌드가 인쇄하는 두 번째check를 실행합니다.check --at <설정 비트 시간>: 기본 샘플은 종종 초점이 흐려진 순간에만 위치하며, 키트가 대비 검사에서 제품 텍스트를 숨깁니다(의도적으로 흐려짐). 따라서contrast ... checked 0은 시청자가 읽는 것을 감사하지 않았습니다.check만으로는 충분하지 않습니다: 이동하는 항목이 경로의 대부분에서 보이지 않는 비디오를 통과시켰습니다. 프레임을 확인하세요.- 모든 설정 비트를 스냅샷으로 찍고 각 이미지를 직접 확인하세요. build.py에서
b.snap(t, label)로 표시합니다. 빌드는 정확한 명령을 인쇄합니다:npx --yes [email protected] snapshot . --at 3.2,4.7,9.98 --no-end --describe false -o snapshots/setup--no-end는 해당 시간만 캡처합니다.--describe false는 프레임이 외부 비전 API로 전송되는 것을 방지합니다. 프레이밍(가장자리에서 잘린 것 없음), 대상 위의 커서, 자연 크기로 중앙에 배치된 팝업, 온전한 제목을 확인하세요.--zoom "#toast" --zoom-scale 2는 하나의 요소를 자릅니다. 의심스러운 트윈을 테스트하려면--at <start>,<later>가--at <later>와 일치해야 합니다. - 렌더링합니다. 검토용 드래프트, BRIEF.md가 서명되면 최종본(build.py가 이 줄을 인쇄합니다):
그런 다음 MP4에서 render-qa를 실행합니다. 모든 버전의 MP4를 보관합니다.npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality draft npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality delivery
서명 게이트
build.py는 coverage_signed_by 및 claims_signed_by가 BRIEF.md에 설정될 때까지 빌드를 거부합니다(종료 코드 2).
--draft는 어쨌든 빌드하고 <meta name="pvs-draft" content="1">을 index.html에 스탬프합니다.
QA는 보고서를 드래프트로 표시하고 최종본은 거부합니다. 검토자를 대신하여 서명하지 말고,
메타를 제거하지 마세요: 드래프트는 보기 위한 것이며, 제공하기 위한 것이 아닙니다.
이유: 이 기술이 비롯된 프로덕션에서 26개 버전 중 9개는 비디오가 검토자가 관심을 가진 기능을 설명하지 않았고, 아무도 빌드하기 전에 해당 기능을 기록하지 않았기 때문에 발생했습니다. 게이트는 합의가 먼저 오도록 합니다.
사고로 인한 규칙
- 프로덕션 결함은 수정하고, 외관은 유지하세요. 레이아웃, 토큰 및 동작은 1:1로 유지하지만, 라이브 앱의 가시적인 결함(누락된 패딩, 넘치거나 잘린 텍스트, 회색 기본 컨트롤, 클릭 후 남은 포커스 링)을 수정하세요. 모든 수정 사항을 BRIEF.md 노트에 나열하세요.
- 제품이 구성 가능할 때 구성 가능한 것을 표시하세요: 구매자가 물어볼 만한 설정은 내레이션뿐만 아니라 화면에 표시되어야 합니다.
- 메뉴 위에 모달을 열기 한 프레임 전에 메뉴를 닫으세요. 열린 드롭다운 아래 새 대화상자는 한 렌더링에서 고스트 텍스트를 남겼습니다.
- 엔드 화면 콘텐츠만 록업으로 페이드하고, 록업이 나타날 때까지 배경을 유지하세요.
둘 다 페이드하면 그 사이에 날카로운 UI 프레임이 나타났습니다(
S.lockup이 이렇게 함). - 클릭 전에 호버(
hov클래스 약 0.12초 전), 첫 번째 랙 후 커서가 들어오고 엔드 화면 전에 커서가 나갑니다. - UI, 데이터 또는 내레이션에 공급업체 또는 금지된 이름이 없습니다(product.yaml
banned_terms,names). 실제 화면에 하나가 표시되면 해당 조각을 프레임 밖으로 유지하고, 절대 비어 있는 상태로 두지 마세요. - 진행 상황을 일찍 보여주기 위해 렌더링하지 마세요. 스냅샷으로 반복하고, 설정 비트가 올바르게 보일 때 렌더링하세요.
파일
| 경로 | 언제 읽을 것인가 |
|---|---|
references/stage-kit.md | 헬퍼의 시그니처, 플레이스홀더, CSS 변수 또는 buildlib API가 필요할 때 |
references/beat-recipes.md | 특정 비트(오프닝, 챕터, 클릭, 타이핑, 스트리밍, 팝업, 드롭다운, 토스트, 스크롤, 푸시인)를 구축할 때 |
references/framing-and-pacing.md | 프레이밍 또는 리듬을 선택하거나, 검토자가 "확대됨", "빠름", "혼란스러움"이라고 말할 때 |
references/end-screen-and-lockup.md | 엔딩을 구축할 때 |
references/ui-component-library.md | UI 조각이 둘 이상의 비디오에 나타나거나, 다른 비디오에서 마크업을 복사하려고 할 때 |
scripts/buildlib.py | API 참조에서 다루지 않는 동작이 필요할 때 |
kit/stage.js | 타임라인 헬퍼에 대해 동일함 |
PVS_HOME/_template/video/video/ | 모든 새 비디오가 시작하는 예제 build.py, template.tpl 및 app.css |