Communitygithub.com

scroll-motion

GSAP, ScrollTrigger, Lenis를 사용하여 스크롤 기반 및 등장 애니메이션(리빌, 패럴랙스, 고정 섹션, 가로 스크롤, 라인 드로잉, 카운터, 프리로더)을 웹사이트에 추가합니다.

scroll-motion란 무엇인가요?

이 스킬은 고급 웹 애니메이션을 구현하려는 개발자를 위한 종합 가이드입니다. '프리미엄'한 느낌의 웹사이트, 부드러운 스크롤, 패럴랙스, 텍스트 리빌, 고정 스크롤 섹션, 애니메이션 프리로더가 필요하거나 GSAP, ScrollTrigger, Lenis, Locomotive, AOS 같은 라이브러리를 언급할 때 사용합니다. GSAP, ScrollTrigger, Lenis를 설정하는 방법부터 각 효과(리빌, 이미지 효과, 고정, 기본 효과)를 코드로 바로 사용할 수 있도록 안내합니다. 단순한 장식이 아닌, 각 애니메이션을 콘텐츠 구조 전달(새 섹션 알림, 항목 간 관계 표시, 순서 강조 등)이라는 목적에 연결시켜 성능을 최적화합니다. 또한 접근성을 위해 `prefers-reduced-motion` 미디어 쿼리를 존중하고, 모바일에서는 고정/가로 스크롤을 비활성화하며, 작은 사이트의 경우 IntersectionObserver와 CSS 트랜지션 같은 가벼운 대안을 제시합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imperfec-t/webcraft/tree/main/skills/scroll-motion

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

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

문서

Scroll motion

모션은 구조를 설명해야 합니다: 무엇이 새로운지, 무엇이 함께 속하는지, 다음에 무엇을 봐야 하는지. 이러한 기능을 수행하지 않는 애니메이션은 단순한 장식에 불과하며 성능을 저하시킵니다. 따라서 아래 각 효과는 특정 목적에 연결되어 있습니다.

설정

<script defer src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/lenis@1/dist/lenis.min.js"></script>
<script defer src="/js/main.js"></script>

defer는 스크립트가 첫 페인트를 차단하지 않도록 하면서도 순서대로 실행되도록 하여, main.js(아래 코드)가 gsap을 볼 수 있게 합니다. 프로덕션에서는 정확한 버전([email protected])을 지정하거나 파일을 직접 호스팅하세요.

gsap.registerPlugin(ScrollTrigger);

const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
if (!reduce) {
  const lenis = new Lenis({ duration: 1.1, smoothWheel: true });
  lenis.on("scroll", ScrollTrigger.update);
  gsap.ticker.add((t) => lenis.raf(t * 1000));
  gsap.ticker.lagSmoothing(0);
}

모든 애니메이션을 if (!reduce)로 감싸거나 gsap.matchMedia()를 사용하세요. 전정 장애가 있는 사용자는 이유가 있어 해당 환경 설정을 지정한 것이며, 콘텐츠는 모션 없이도 완전히 볼 수 있어야 합니다.

효과 선택하기

목적효과참조 섹션
새 섹션 알림마스크된 헤드라인 리빌Reveals
항목들이 함께 속함을 표시지연된 페이드 업Reveals
이미지에 깊이 추가패럴랙스, clip-path 리빌Images
순서 전달고정 단계, 선 그리기Pinning
작업 범위 표시가로 스크롤Pinning
숫자 강조카운트 업Details
초기 로딩 커버프리로더Details

각 효과에 대한 바로 사용 가능한 코드는 references/snippets.md에 있습니다. 효과를 구현하려고 할 때 이 파일을 읽으세요. 계획 단계에서는 필요하지 않습니다.

규칙

  • transform과 opacity만 애니메이션 처리하세요. top, width, margin 또는 box-shadow를 애니메이션 처리하면 매 프레임마다 레이아웃 또는 페인트가 트리거되어 중간 수준의 휴대폰에서 버벅거립니다.
  • 지속 시간: 리빌은 0.61.0초, 호버는 0.20.3초. 더 길면 두 번째 방문 시 느리게 느껴집니다.
  • 이징: 진입에는 power3.out, 전환에는 power2.inOut, 스크러브 애니메이션에는 none (스크러브가 이징을 제공합니다).
  • 스태거: 0.06~0.12초. 총 시간을 제한하세요: 카드가 12개인 경우 처음 6개만 스태거하고 나머지는 함께 처리합니다.
  • 한 번만 재생하세요. once: true 또는 toggleActions: "play none none none"을 사용하세요. 다시 스크롤할 때마다 애니메이션을 다시 실행하면 지루합니다.
  • 페이지당 하나의 쇼피스. 고정 또는 가로 섹션은 한 번은 기억에 남지만 세 번 사용하면 지치게 됩니다.
  • 초기 상태는 JS로 설정하고 CSS로 설정하지 마세요. 스크립트 로드에 실패하면 CSS로 숨겨진 콘텐츠는 영원히 숨겨진 상태로 남습니다.
  • 레이아웃 변경 후 새로고침: 폰트와 이미지가 로드된 후 ScrollTrigger.refresh()를 호출하지 않으면 트리거 위치가 어긋납니다.
window.addEventListener("load", () => ScrollTrigger.refresh());
document.fonts?.ready.then(() => ScrollTrigger.refresh());

모바일

  • gsap.matchMedia()를 사용하여 768px 미만에서 고정 및 가로 스크롤을 비활성화하고 콘텐츠를 일반적으로 쌓습니다.
  • Lenis의 터치 부드러운 스크롤은 종종 네이티브 모멘텀과 충돌합니다. 사용자가 요청하지 않는 한 터치 스크롤은 네이티브(기본값)로 유지하세요.
  • 작은 화면에서는 패럴랙스 거리를 절반으로 줄이세요.

디버깅

  • ScrollTrigger에 markers: true를 추가하여 시작 및 끝 라인을 확인하세요.
  • 고정 시작 시 점프가 발생하면 일반적으로 고정된 요소에 변환 부모가 있거나 높이가 변경되기 때문입니다.
  • 애니메이션이 너무 일찍 실행됨: 위에 있는 이미지가 늦게 로드된 것입니다. 이미지에 명시적인 width와 height를 설정하세요.
  • 아무것도 애니메이션되지 않음: 플러그인이 등록되었는지, 선택자가 일치하는지 확인하세요.

GSAP 없이

작은 사이트에서 간단한 페이드 업의 경우, 클래스를 추가하는 IntersectionObserver와 CSS 트랜지션으로 충분하며 약 70KB를 절약할 수 있습니다. references/snippets.md의 마지막 섹션을 참조하세요.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

hero-section

Design and build the hero (first screen) of a website, including headline layout, media treatment, CTA, proof badge, marquee and entrance animation. Use this whenever someone asks for a hero section, a landing page header, "the top of my homepage", a cinematic or animated intro, a video background, a text marquee, or says their first screen looks plain or generic.

homepage-blueprint

Plan the section structure and content slots of a homepage for an agency, freelancer, studio or service business before any design or code. Use this whenever someone asks "what sections should my homepage have", "plan my website", "structure a landing page for my business", wants a wireframe or sitemap for a service site, or starts building a homepage without a clear outline.

responsive-layout

Build page layouts that work from phones to wide desktops using CSS grid, flexbox, container queries and fluid sizing, including card grids, bento grids, split sections, sticky sidebars and navigation that collapses. Use this whenever someone says their site "breaks on mobile", asks for a responsive grid, a bento layout, a mobile menu, fixing horizontal scroll or overflow, or is laying out any multi-column section.

website-workflow

Plan and sequence a whole website build, from structure through design, code, WordPress and launch, by routing each stage to the right webcraft skill. Use this when someone asks to "build me a website", "design my site from scratch", "redo our homepage", wants an end-to-end plan for a marketing, agency, studio or service site, or the request spans more than one of structure, look, layout, motion, CMS and QA.

관련 스킬