name: scrolline-deck description: 발표 브리프를 스크롤로 진행하는 발표 덱(Scrolline v2)으로 만든다. 무대 1개·연속 timeline 1개·handoff move·컨셉 6종(rail·data·launch·zoom·canvas·kinetic)별 움직임 문법. deck.yaml 작성 → node plan 확인 → 브라우저 smoke → HyperFrames MP4 내보내기까지. 트리거 — "스크롤 덱 만들어", "스크롤 발표", "스크롤텔링 덱", "스크롤로 넘어가는 발표자료", "연표 덱", "데이터 스토리 덱", "제품 발표 스크롤", "줌 드릴다운 발표", "덱을 MP4로", "scrolline", "scrolline deck", "scroll deck", "scrollytelling deck", "scroll-driven presentation", "export deck to mp4". 후속 — "이 beat만 move 바꿔", "정지점 추가", "홀드 길게", "컨셉 바꿔서", "smoke 다시", "MP4 다시 뽑아" 도 이 스킬. ※ 이산 슬라이드·발표자 노트 중심이면 slideshow, 덱과 무관한 영상 제작이면 hyperframes 소관.

scrolline-deck — 스크롤 발표 덱 (v2)

• 산출물: decks/<id>/ 덱 1개(브라우저 발표용) + out/export/<id>.mp4(선택)
• 작업 위치: 이 SKILL.md가 있는 레포 루트. 다른 폴더에서 호출되면 레포 루트로 이동 후 진행(cd ~/.claude/skills/scrolline-deck 등). 모든 명령은 레포 루트 기준
• 정본: plan/CONTRACTS.md(인터페이스), 사용 문서 docs/*.md. 이 파일과 문서가 다르면 CONTRACTS가 우선

원칙

1. 내용은 beat, 움직임은 move: deck.yaml에는 내용과 move 이름·params만. 덱을 위해 engine·moves 코드를 고치지 않는다. 덱 고유 장면이 꼭 필요하면 decks/<id>/sequences/<use>.js(type: sequence)
2. 컨셉 문법 준수: 컨셉 moves.allow 밖 move는 쓰지 않는다(불가피하면 override: "<사유>"). 컨셉 moves.signature move는 덱에서 1회 이상 사용
3. 컷 대신 handoff: 이어지는 두 beat가 같은 대상(숫자·막대·사건·글자)을 다루면 link move로 잇는다. link가 B를 다 그리면 B의 enter는 engine:none
4. 수치 날조 금지: 실데이터 덱(sample: false)은 number·chart·quote·photo·값 있는 compare마다 source 필수, sources[]에 url·확인일. 가상 회사면 sample: true(화면에 「표본」 표기)
5. 한 정지점 = 한 주장: 정지점마다 초점 1개, 글자 위계 3단(결론·보충·출처) 이내. 메타 캡션(「25초」「녹화」 등) 금지
6. 3D는 카메라만: 설명용 3D 오브젝트 금지. 깊이·기울기는 camera family move와 data-depth 층으로만

절차

1. 브리프 정리

• 확인 항목: 주제, 청중, 발표 길이, 결론 1문장, 보유 자료(수치·출처·영상·사진), 실데이터/표본 여부, 언어(ko|en)
• 정지점 수 기준: 발표 1분당 정지점 1~2개
• 출처 없는 수치는 사용자에게 출처를 받거나 표본으로 전환. 임의 수치 생성 금지

2. 컨셉 선택

• 허용 beat type·move·기본값: concepts/<id>/concept.json. 참고 덱: 컨셉마다 decks/ 예제 1편
• 사용자에게 컨셉과 beat 목록(id·type·한 줄 내용·정지점)을 표로 보여 주고 합의 후 작성

3. 덱 생성·작성

npm run deck -- new <deckId> --concept <concept>
npm run deck -- moves --family <family> --role <role>   # 쓸 수 있는 move 목록

• decks/<deckId>/main.js의 boot({...})에 mode: import.meta.env.SCROLLINE_MODE가 있는지 확인(없으면 추가. MP4 내보내기 필수 조건)
• deck.yaml 필드: docs/writing-a-deck.md. beat type별 필수 필드·part: CONTRACTS C4
• move params: 해당 moves/<family>/<id>.js의 params(doc·min·max). 범위 밖 값은 검증 실패
• 같은 move를 같은 role로 2회 이상 쓰면 repeat: intended(의도된 리듬일 때만)
• 영상: 스크럽 = npm run frames -- <in.mp4> decks/<id>/assets/frames/<name> 후 mode: scrub + frames. 재생 = mode: play|loop. 스톡은 라이선스와 출처를 decks/<id>/assets/CREDITS.md에 기록(docs/media.md)

4. 정지점 확인(node)

npm run deck -- plan <deckId>

• 확인: 정지점 순서·간격, 빈 구간 없음, step 정지점(<beat>/<step>) 위치
• 정지점 간격이 너무 짧으면 hold·move duration, 너무 길면 timing.unit·overlap 조정

5. 브라우저 smoke

npm run dev -- --port 5190                              # 별도 터미널
node tools/smoke.mjs <deckId> --driver chrome --shots

• 결과: out/smoke/<deckId>/report.json, stop-XX.png, sheet.png
• 통과 기준: errors 0, empty 0, overlaps 0, clipped 0, tiny 0
• sheet.png를 직접 열어 정지점마다 원칙 5(초점 1개·위계·메타 캡션) 판정

6. MP4 내보내기(요청 시)

npm run export -- <deckId> --dry-run    # 길이·발표 경로 확인
npm run export -- <deckId>              # out/export/<deckId>.mp4
npm run capture -- <deckId> --stops     # 정지점 PNG, out/capture/<deckId>/

• 정지점별 머무는 시간: beat exportHold(초), 기본 1.6초
• 배경 음악·이어 붙이기는 ffmpeg 후처리(도구 범위 밖)

게이트(전부 통과해야 완료 보고)

금지

• 덱 하나를 위해 engine/·moves/·concepts/ 수정(필요하면 별도 작업으로 분리, docs/moves.md·docs/concepts.md 절차)
• tl.from·Math.random·Date.now·tween 값 안 var((move 작성 시)
• 출처 없는 실수치, 표본 덱의 실존 회사·인물 이름
• Playwright로 캡처(캡처는 capture·smoke 경로만)

참고 문서

• docs/getting-started.md: 설치부터 MP4까지
• docs/writing-a-deck.md: deck.yaml 필드·beat type·내용 감사
• docs/concepts.md: 컨셉 팩 6종·새 컨셉 추가
• docs/moves.md: move 계약·작성·테스트
• docs/media.md: 프레임 시퀀스·영상·마스크
• docs/export.md: 내보내기·캡처·smoke
• docs/architecture.md: 층 구조·timeline 모델·개발 원칙·state 기록

You write a deck.yaml. Scrolline lays every beat on one paused GSAP timeline, the mouse wheel scrubs it, presenter keys jump between stops, and the same timeline renders to MP4.

Why v2

• v1 reused 12 scene templates, so every deck read as the same deck with new pictures. v2 has no scenes: a deck is one continuous master timeline on one stage.
• Beats hand off instead of cutting. A link move carries part of one beat (a bar, a dot, a date) into the place it holds in the next beat, so the audience follows one object rather than a slide change.
• Each concept has its own motion grammar. A concept pack fixes the camera axis, timing and allowed moves, and names signature moves the deck must use. The six example decks move differently because their grammars differ.

Adding video? Issue your own Pexels or Pixabay API key first and keep it in .env (git-ignored, blocked by npm run check). See docs/media.md.

Example decks

Six decks, one per concept. Decks marked sample use a fictional company and say so on screen. The others use real data with a source list in deck.yaml.

The decks are in Korean. See docs/concepts.md for what each concept allows.

Quick start

Requires Node.js 22 or newer. ffmpeg is needed only to cut frame sequences, and the HyperFrames CLI (fetched by npx) only to export MP4.

git clone https://github.com/gongnyang/awesome-html-scrolline-deck.git
cd awesome-html-scrolline-deck
git checkout v2
npm install
npm run dev

Open http://localhost:5173/decks/rail-ai-decade/ and scroll, or press →.

Start your own deck from a concept:

npm run deck -- new my-review --concept data   # decks/my-review/{deck.yaml,index.html,main.js,assets/}
# write beats in decks/my-review/deck.yaml
npm run deck -- plan my-review                  # stops and timings, computed in node
npm run export -- my-review                     # out/export/my-review.mp4

The full walkthrough is in docs/getting-started.md, and every deck.yaml field is in docs/writing-a-deck.md.

A beat in deck.yaml

- id: b-trend
  type: chart
  kind: bar
  categories: ["Q1", "Q2", "Q3"]
  series:
    - { name: "Revenue ($M)", values: [3.1, 3.6, 4.2] }
  title: "Each quarter added about $0.5M"
  states:
    - name: steps
      notes:
        - { index: 1, text: "+0.5" }
        - { index: 2, text: "+0.6" }
  place: { slot: full }
  steps:
    - { name: steps, move: annotation-pin }   # a stop after the step

Beats hold content and moves hold motion. A beat renderer draws only the finished state. The concept supplies default moves, and each beat can name its own enter, exit, link, steps, camera or ambient move.

Structure

flowchart TD
  site["site/ (gallery)"] --> decks
  decks["decks/<id>: deck.yaml, main.js, assets/, sequences/"] --> concepts
  concepts["concepts/<id>: concept.json, tokens.css"] --> moves
  moves["moves/<family>/<id>.js: enter, exit, link, step, camera, ambient"] --> engine
  engine["engine/: stage, plan + build, scroll, presenter, handoff, media, export"]
  tools["tools/: cli, check, export, capture, smoke"] -.-> decks
  tools -.-> engine

• engine knows nothing about content. It renders beats, plans the timeline in node (no DOM), builds the master timeline, drives it from scroll and keys, and exports.
• moves are small units of motion with a fixed contract: pure timing, deterministic build, no tl.from, no clock or Math.random. Each move ships with a test.
• concepts pick a camera axis, timing, eases, tokens and an allow list of moves.
• decks are data plus assets. Deck-only scenes go in sequences/.

Imports only go downward, and npm run check blocks upward imports, cycles and imports across sibling folders. See docs/architecture.md.

Presenter keys

The wheel and the keys move the same scroll position. A key press travels to the next stop in 0.9 to 2.6 s, depending on distance. With reduced motion, or with ?motion=reduce, the jump is instant and moves fall back to fades of the same length, so every stop lands at the same time.

Video

Scrubbed video uses frames rather than video.currentTime so that seeking is exact in both directions on every browser. See docs/media.md.

MP4 export

npm run export -- rail-ai-decade                # out/export/rail-ai-decade.mp4
npm run export -- rail-ai-decade --dry-run      # print the timeline map and path only
npm run capture -- rail-ai-decade --stops       # one PNG per stop in out/capture/rail-ai-decade/

Export replaces scrolling with a presentation path. It travels from stop to stop, holds 1.6 s on each one (exportHold per beat), and renders the paused timeline through HyperFrames at 1920×1080. Because the timeline depends only on time, the MP4 shows the same frames as the browser. See docs/export.md.

Tests and CI

npm test         # vitest + happy-dom: engine modules, every move, every deck
npm run check    # dependency rules, a test next to every module, state schemas, move static rules
npm run ci       # both; the merge condition

Move tests run a shared contract check: seek determinism, rewind to the initial state, no blur or 3D under reduced motion, and handoff landing within 1 px. GitHub Actions runs npm ci, npm test and npm run check on every push to main and v2, and on every pull request.

Use it from Claude Code

SKILL.md makes this repository a Claude Code skill named scrolline-deck. It takes you from a brief to a concept, then deck.yaml, a smoke run and the MP4. Link the checkout into your skills folder:

ln -s "$PWD" ~/.claude/skills/scrolline-deck

Repository layout

engine/      stage, timeline plan/build, scroll, presenter, handoff, media, export, beat renderers
moves/       move library by family (reveal, type, morph, camera, rail, data, media, assemble, emphasis)
concepts/    concept packs: concept.json + tokens.css
decks/       example decks: deck.yaml + main.js + assets/
tools/       cli, checks, export, capture, smoke, frame extraction
site/        gallery
docs/        guides
plan/        design source of truth (Korean): PLAN, ARCHITECTURE, CONTRACTS
state/       board.json + runs.jsonl build-state log

Contributing

See CONTRIBUTING.md. In short, keep commits small, put a test next to every module, keep each commit to one hat (Hat: feature or Hat: refactor), and run npm run ci before a pull request.

License and credits

Code: MIT © gongnyang.

• Motion sources. Every move lists the techniques it borrows from in sources, using slugs from awesome-ai-motion.
• References. Scroll stories and keynotes such as The Pudding, Our World in Data, The New York Times, Codrops and Apple product pages were studied for ideas only. No code or assets from them are included.