Communitygithub.com

hemangjoshi37a/scroll_animated_webpages_skill

수상 경력에 빛나는 스크롤 애니메이션 웹사이트를 처음부터 끝까지 구축합니다. 발견 마법사(인물/제품/회사/이벤트/원인)를 실행하고, Scroll Score 청사진을 작성하며, 프로젝트를 스캐폴딩하고, GSAP ScrollTrigger 모션(선택적으로 Lenis 부드러운 스크롤)을 구현한 후, Playwright MCP로 실제 브라우저에서 검증하고 발견된 문제를 수정합니다. 사용자가 스크롤 애니메이션 사이트, 스크롤 기반 랜딩 페이지, Apple 스타일 제품 스크롤, awwwards 스타일 사이트, 스크롤텔링, 패럴랙스 또는 고정 섹션, 이미지 시퀀스 스크롤 효과를 원할 때 사용하세요.

scroll_animated_webpages_skill란 무엇인가요?

이 스킬은 사용자에게 스크롤 중심의 완전한 웹사이트를 제공하는 엔드투엔드 빌더입니다. Phase 1의 대화형 마법사를 통해 주제 유형(인물, 제품, 회사 등)과 목표를 파악한 후, 더 이상 사용자에게 질문하지 않고 자율적으로 나머지 단계(Phase 2~6)를 실행합니다. Phase 2에서는 Scroll Score라는 JSON 청사진을 작성하여 각 스크롤 순간(비트)을 계획하고, Phase 3에서는 AI 이미지 생성 MCP를 활용하여 실제 에셋을 확보합니다. Phase 4에서는 Vite + vanilla TypeScript + GSAP(무료) 기반으로 프로젝트를 스캐폴딩하고, Phase 5에서 패턴 라이브러리(예: 핀-스크러브, 미디어 스크롤 시퀀스)를 사용하여 각 비트를 구현합니다. 마지막으로 Phase 6에서는 Playwright MCP로 실제 브라우저를 구동하여 스크롤 위치별로 스크린샷, 콘솔 오류, 네트워크 요청 등을 자동 검증하고, 문제가 발견되면 최대 5회까지 수정 및 재검증을 반복합니다. 이 스킬은 코드 리뷰만으로는 발견하기 어려운 핀 충돌, 트리거 오작동, 프레임 누락 등 스크롤 애니메이션의 실제 결함을 잡아내는 데 특화되어 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hemangjoshi37a/scroll_animated_webpages_skill/tree/HEAD/skills/scroll-animated-site

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

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

문서

스크롤 애니메이션 사이트 빌더

사용자로부터 주제와 대상(subject)을 입력받아 완전하고 검증된 스크롤 기반 웹사이트를 제공합니다. 중간에 작업을 다시 사용자에게 넘기지 않습니다.

시작하기 전: 새 사이트인가요, 리트로핏인가요?

이미 순위가 있는 페이지에 모션을 추가하는 것은 다른 작업이며 다른 위험이 따릅니다. 스크롤 예산에 기존 페이지 높이가 포함되어야 하며, 고정(pin)은 결정을 내리기 위해 페이지를 스캔하는 사용자에게 죽은 스크롤 거리입니다. 기본적으로 별도의 쇼케이스 URL에 구축하고 링크를 제공하세요. 페이지가 트래픽을 잃을 위험이 없고, 참조보다는 인상이 목적인 경우에만 기존 페이지를 그대로 변환하세요. 항상 먼저 바이트 단위 백업을 수행하고 사용자에게 복원 명령을 전달하세요. 리트로핏에 동의하기 전에 references/08-failure-modes.md §3을 읽으세요.

파이프라인

6단계. 순서대로 실행하세요. Phase 1만 사용자와 대화합니다.

1 DISCOVER  → 마법사, 2~3 라운드 질문                  [대화형]
2 SCORE     → scroll-score.json 청사진 컴파일            [자율]
3 ASSETS    → 이미지, 프레임, 비디오 생성/수집        [자율]
4 SCAFFOLD  → 프로젝트 스켈레톤 + 모션 런타임        [자율]
5 BUILD     → Score의 모든 비트 구현                    [자율]
6 VERIFY    → 실제 브라우저 구동, 수정, 반복            [자율]

Phase 1에서 마법사가 종료된 후에는 질문을 중단하세요. Phase 2~6은 자체 판단으로 완료될 때까지 실행합니다. 가정 사항은 DECISIONS.md에 기록하고, 최종 보고서에 보고하세요. 사용자는 엔드투엔드 빌드를 요청했습니다. 반쯤 완성된 페이지와 질문은 실패한 실행입니다.


Phase 1 — DISCOVER (마법사)

AskUserQuestion 도구를 사용하여 질문하세요. 긴 문단으로 질문하지 마세요. 일반적으로 2라운드, 최대 3라운드입니다. 전체 질문 은행은 분기별로 제공:

→ references/01-discovery-wizard.md 읽기

1라운드는 항상 동일한 두 가지 질문입니다. 주제 유형과 주요 목표:

주제스크롤이 실제로 하는 일
인물 (포트폴리오, 이력서, 개인 브랜드)신뢰 구축: 작업 → 증거 → 연락처
제품 (물리적 또는 디지털)객체 공개: 히어로 → 기능 → 구매
회사 (에이전시, 스타트업, 스튜디오)규모 구축: 매니페스토 → 작업 → 팀
이벤트/런칭 (컨퍼런스, 드롭, 출시)기대감 조성: 날짜 → 라인업 → 등록
원인/스토리 (비영리, 사설, 보고서)주장 전달: 갈고리 → 증거 → 행동

선택한 분기에 따라 섹션 스켈레톤과 지배적인 모션 패턴이 결정됩니다. 2라운드는 분기별 특정 질문(어떤 작업, 어떤 제품, 어떤 증거)을 묻습니다. 3라운드는 여전히 모호할 경우에만 미적 방향, 모션 강도 및 에셋 전략을 결정합니다.

다음을 명명할 수 있는 즉시 마법사를 중단하세요: 주제, 목표, 4~7개 섹션, 미적 방향, 에셋 출처. 나머지는 추론합니다.


Phase 2 — SCORE (청사진)

모든 것을 프로젝트 루트의 scroll-score.json으로 컴파일하세요. 이것은 빌드와 검증기가 모두 읽는 계약입니다. 컴포넌트를 작성하기 전에 먼저 작성하세요.

→ 전체 스키마는 references/02-scroll-score.md 읽기

Score는 비트(beat) 의 목록입니다. 하나의 비트 = 하나의 스크롤 기반 순간: 무엇을 고정(pin)하고, 무엇을 스크러브(scrub)하며, 얼마나 많은 거리에서, 무엇이 움직이는지를 정의합니다.

{
  "meta":  { "subject": "…", "type": "product", "goal": "…", "stack": "vite-vanilla" },
  "theme": { "bg": "#0a0a0a", "fg": "#fafafa", "accent": "#ff4d17", "font": { … } },
  "motion":{ "intensity": "cinematic", "smoothScroll": false, "reducedMotion": "degrade" },
  "beats": [
    { "id": "hero", "pattern": "media-scrub-sequence", "pin": true,
      "scrub": 1, "start": "top top", "end": "+=200%", "frames": 48, … },
    { "id": "features", "pattern": "sticky-stack", … }
  ]
}

스크롤 예산을 세우세요. 총 페이지 높이는 100vh × (1 + Σ 비트 스크롤 비용)에 근접해야 합니다. 고정 스크러브 비트는 1.52.5 뷰포트 높이를 소비하고, 나타나기(reveal) 비트는 약 1을 소비합니다. 총 3 미만이면 사이트가 갑작스럽게 느껴지고, 12를 초과하면 지루하게 느껴집니다. 59를 목표로 하세요.


Phase 3 — ASSETS

회색 박스를 절대 출시하지 마세요. Score에 명명된 모든 비트는 Phase 5 이전에 실제 에셋이 필요합니다. 플레이스홀더로 빌드하면 항상 다시 작업해야 합니다.

→ 전체 파이프라인(렌더링 → 보간 비디오 → 프레임 시퀀스 체인, 모든 ffmpeg 호출 및 가중치 예산 포함)은 references/05-asset-pipeline.md 읽기

세 가지 출처, 선호도 순:

  1. 사용자 제공 — 항상 우선. 마법사에서 요청하고, 이후에는 요청하지 마세요.
  2. 생성 — mcp__image-gen-mcp__generate_image (gpt-image-2, 제품의 경우 background: "transparent", 최대 3840x2160), 또는 edit_image를 사용하여 실제 제품 사진을 스타일리시한 렌더링으로 변환.
  3. 플레이스홀더 — 사용자가 명시적으로 연기한 비트에만 사용하며, 의도된 그라디언트/타이포그래피 구성이어야 하고, 절대 회색 박스가 아니어야 합니다.

이미지 시퀀스 히어로(Apple 스타일 "제품이 스크롤에 따라 분해되는")의 경우 체인은 다음과 같습니다: 첫 번째 프레임 + 마지막 프레임 → 보간 비디오 → 추출된 프레임 → WebP 시퀀스 → 캔버스 스크러브. 시퀀스를 총 4MB 미만, 36~60프레임, 1600px 너비로 유지하세요. 이 예산이 효과가 사용 가능하게 유지되는 유일한 이유입니다. 예산 초과는 이 패턴의 가장 흔한 실패 원인입니다.


Phase 4 — SCAFFOLD

사용자가 지정하지 않은 경우 기본 스택: Vite + vanilla TS + GSAP. 프레임워크 수명 주기와 싸울 필요가 없으며, React에서 ScrollTrigger 버그는 거의 항상 정리(cleanup) 버그입니다. 사용자가 요청하거나 프로젝트에 라우팅이 필요한 경우에만 Next.js/React를 사용하고, 그때도 useGSAP()를 사용하여 정리하세요. 절대 useEffect를 직접 사용하지 마세요.

부드러운 스크롤(Lenis)은 OPT-IN입니다. 더 이상 기본 스택의 일부가 아닙니다. 사용자가 부드러운 스크롤 또는 관성 스크롤을 이름으로 요청한 경우에만 추가하세요. Lenis는 네이티브 스크롤을 자체 애니메이션 위치로 대체하며, 조금이라도 잘못 느껴지면 전체 페이지가 깨진 것으로 읽힙니다. 이것은 기술적으로 올바른 빌드가 거부되는 가장 흔한 이유입니다. ScrollTrigger의 scrub은 이미 사람들이 "부드러운"이라고 말할 때 일반적으로 의미하는 이지드(eased), 영화 같은 느낌을 제공합니다. references/08-failure-modes.md §1을 참조하세요.

→ 스캐폴드 및 정확한 명령어는 references/07-stack-setup.md 읽기

GSAP는 v3.13부터 100% 무료(Webflow 인수)이며 SplitText, ScrollSmoother 및 MorphSVG를 포함합니다. npm install gsap으로 모든 것을 얻을 수 있습니다. 라이선스 키, gsap-trial, CDN 플러그인 해결 방법이 필요 없습니다. 플러그인이 유료라고 사용자에게 말하지 마세요.

콘텐츠는 src/content.ts에 있으며, 마크업에 인라인으로 절대 포함하지 마세요. 사용자가 모션 코드를 건드리지 않고 카피를 변경할 수 있어야 합니다.


Phase 5 — BUILD

표준 패턴 구현을 사용하여 Score의 각 비트를 구현하세요:

→ references/03-pattern-library.md 읽기 — 12가지 패턴, 바로 사용 가능.

패턴용도
reveal-on-enter표준 섹션 진입, 카드 그리드
text-reveal헤드라인, 인용구 (SplitText, 마스크)
pin-scrub핵심 "와우" 순간 — 고정된 스테이지, 스크러브된 타임라인
parallax-layers깊이: 배경, 전경 소품
media-scrub-sequenceApple 스타일 제품 공개 (캔버스 + 프레임)
media-scrub-video비디오 파일에서 동일한 효과 (currentTime)
horizontal-scroll포트폴리오, 갤러리, 타임라인
mask-reveal이미지가 열리며 뷰포트를 삼키는 효과
sticky-stack기능 목록, 카드 쌓기
scroll-progress진행 표시줄, 카운터, 섹션 표시기
theme-morph섹션 간 배경/색상 전환
snap-sections덱(deck) 스타일, 스크롤당 한 섹션 페이지

그리고 절대 타협할 수 없는 GSAP 규칙:

→ ScrollTrigger 코드를 작성하기 전에 references/04-gsap-rules.md 읽기

빌드를 가장 자주 망가뜨리는 5가지:

  1. 타임라인당 하나의 ScrollTrigger, 타임라인에만 적용 — 자식 트윈에는 절대, 부모 타임라인 내에 중첩되지 않음.
  2. Lenis를 추가한 경우(그리고 오직 그 경우에만), GSAP 루프와 공유합니다. lenis.on('scroll', ScrollTrigger.update) + gsap.ticker.add(t => lenis.raf(t * 1000)) + gsap.ticker.lagSmoothing(0). Lenis를 위해 별도의 requestAnimationFrame 루프를 추가하지 마세요.
  3. containerAnimation 또는 미디어 스크러브를 구동하는 모든 트윈에 ease: "none".
  4. 동일한 트리거에 scrub 또는 toggleActions, 둘 다 사용하지 마세요.
  5. 폰트와 이미지가 로드된 후 ScrollTrigger.refresh() — 리사이즈뿐만 아니라.
  6. 핀을 적용하기 전에, 조상 요소에서 transform / filter / contain을 확인하세요. 이 중 하나라도 있으면 position: fixed가 조용히 깨져서, 핀이 생성되고 pin: true를 보고하지만 아무 일도 하지 않습니다. 속성을 제거하거나 pinType: 'transform'을 설정하세요. 08-failure-modes.md §2를 참조하세요.

transform과 opacity만 애니메이트하세요. top, left, width, height, 또는 margin을 건드리는 것은 스크롤 시 프레임 드롭을 유발합니다.


Phase 6 — VERIFY

이 단계는 선택 사항이 아니며, 이 스킬을 GSAP 수동 작성과 차별화하는 요소입니다. 스크롤 애니메이션은 코드를 읽어서 검증할 수 없습니다. 핀은 무너지고, 트리거는 잘못된 깊이에서 발동되며, 프레임은 실제 브라우저의 실제 뷰포트에서만 누락됩니다.

→ 전체 루프 및 체크리스트는 references/06-verification.md 읽기 → references/08-failure-modes.md 읽기 — 모든 자동 검사를 통과하는 실패들. Phase 4 이전에 읽고, 문제가 발생한 후에 읽지 마세요.

개발 서버를 시작하고 Playwright MCP로 구동하세요:

mcp__playwright__browser_navigate      → 개발 서버 URL
mcp__playwright__browser_resize        → 1440×900, 그 다음 390×844
mcp__playwright__browser_evaluate      → 깊이로 스크롤, 상태 읽기
mcp__playwright__browser_take_screenshot → 각 깊이에서
mcp__playwright__browser_console_messages → 오류 및 GSAP 경고
mcp__playwright__browser_network_requests → 404, 에셋 가중치

데스크톱 및 모바일에서 페이지 높이의 0%, 15%, 30%, 50%, 70%, 85%, 100% 를 스위핑(sweep)하세요. 각 지점에서 스크린샷을 찍고 확인하세요. 페이지가 올바르게 보이는지 확인하는 것이지, 단지 오류가 발생하지 않았는지 확인하는 것이 아닙니다.

실제 입력으로 페이지를 구동하세요 — mouse.wheel() 또는 키 입력. 절대 window.scrollTo를 사용하지 마세요. 합성 스크롤링은 스크롤 하이재킹 라이브러리에 의해 무시되며, 이것이 바로 잡아야 할 실패입니다. 휠 노치 세 번으로 페이지가 움직이지 않으면, 어설션이 무엇을 말하든 깨진 것입니다.

다음 중 하나라도 해당되면 실행을 실패로 처리하고 수정하세요:

  • 콘솔 오류 또는 ScrollTrigger 경고
  • 404, 또는 총 에셋 가중치 예산 초과
  • 모든 깊이에서 빈/스타일 없는 스크린샷
  • 다음 섹션과 겹치거나 레이아웃이 무너지는 고정 섹션
  • 절대 표시되지 않는 콘텐츠 (발동되지 않는 reveal)
  • 390px 너비에서 수평 오버플로
  • 소스 어딘가에 markers: true가 남아 있음
  • prefers-reduced-motion 폴백 없음
  • 실제 휠 노치 세 번으로 페이지가 눈에 띄게 움직이지 않음
  • 스테이지가 여전히 스크롤을 추적하는 핀 (범위 내에서 |rect.top| < 10 확인)
  • 스크러브된 미디어가 핀의 ~90% 이전에 끝에 도달
  • 기본 CTA에 도달하기 위해 약 40회 이상의 휠 노치 필요

수정 → 재검증 루프를 최대 5회까지 깨끗해질 때까지 반복하세요. 5회 후에도 여전히 실패하면, 나머지를 출시하고 해당 비트 하나를 플래그 뒤에 비활성화한 후 최종 보고서에 그 사실을 명확히 명시하세요. 검증되지 않은 페이지에 대해 성공을 보고하지 마세요.


완료 조건

  • scroll-score.json이 실제로 빌드된 것과 일치
  • 모든 비트가 데스크톱 및 모바일에서 검증됨
  • 콘솔 오류 0, 404 0개
  • prefers-reduced-motion은 즉시 상태로 저하(degrade)되고 모션 없음
  • Lighthouse 수준의 온전성: 핀으로 인한 레이아웃 이동 없음, 이미지 크기 조정
  • README.md — 실행 방법, 콘텐츠 위치, 에셋 교체 방법
  • DECISIONS.md — 마법사 종료 후 내린 가정
  • 최종 메시지: 무엇이 빌드되었는지, 무엇이 가정되었는지, 무엇을 검토해야 하는지

금지 사항

  • ❌ 마법사 종료 후 질문하지 않음 — 대신 가정하고, 기록하고, 보고할 것
  • ❌ 실제 브라우저에서 Phase 6을 실행하지 않고 완료 보고하지 않음
  • ❌ markers: true, console.log, 또는 TODO를 출시 코드에 포함하지 않음
  • ❌ gsap-trial을 사용하거나 SplitText/ScrollSmoother에 클럽 라이선스가 필요하다고 주장하지 않음
  • ❌ 스크롤 시 레이아웃 속성 애니메이션 금지
  • ❌ 확인 없이 모바일에 핀 적용 금지 — 768px 이하에서는 페이드 인을 선호할 것
  • ❌ 히어로 시퀀스의 에셋 예산 초과 금지

관련 스킬