Communitygithub.com

gsap-motion

GSAP 3 애니메이션 아키텍처 — 플러그인 레지스트리, React 통합(useGSAP), 반응형/접근성 대응, 스크롤 트리거, 텍스트 리빌, Flip 레이아웃 모프, 수평 스크롤, 패럴랙스, 마그네틱/커서 효과, 페이지 전환 등을 위한 포괄적인 스킬입니다.

gsap-motion란 무엇인가요?

이 스킬은 GSAP 3 애니메이션을 활용한 고급 웹 애니메이션 구축을 위한 완전한 아키텍처와 모범 사례를 제공합니다. ScrollTrigger, SplitText, Flip, Observer, Draggable, Inertia, CustomEase, MorphSVG, DrawSVG 등 모든 플러그인이 공개 gsap 패키지에 포함되어 있으며, React 환경에서 `useGSAP` 훅을 통해 안전하게 애니메이션을 관리할 수 있습니다. 주요 기능으로는 `gsap.matchMedia()`를 통한 모션/축소 반응형 브랜치 처리, 스크롤-스크러빙 핀 시퀀스, 텍스트 리빌, clip-path/mask 전환, Flip 레이아웃 모프, 수평 스크롤, 패럴랙스, 마그네틱/커서 효과, 페이지 전환 등이 포함됩니다. 특히 React에서 발생하는 90%의 GSAP 버그를 예방하는 8가지 규칙을 제공하며, Strict Mode 안전성, 메모리 누수 방지, 레이아웃 변경 후 ScrollTrigger 리프레시, 핀(pin) 올바르게 사용하기, 저렴한 속성 애니메이션화, `will-change` 최적화 등을 강조합니다. 이 스킬은 Claude Code, Cursor, Codex 등 모든 AI 에이전트 플랫폼에서 사용할 수 있으며, 스크롤 기반 또는 시네마틱 애니메이션 작업, 경로 변경이나 리사이즈 후 애니메이션이 새거나 중복되거나 끊기는 문제 해결에 특히 유용합니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jakyherr05-hash/Claude-code-skill/tree/HEAD/plugins/premium-web-studio/skills/gsap-motion

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

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

문서

GSAP 모션 아키텍처

확인된 기준 (2026-11-15)

  • [email protected]은 npm의 최신 버전입니다. 라이선스 필드는 "Standard 'no charge' license"(gsap.com/standard-license)로, 클라이언트 작업을 포함한 상업용 사이트에 무료입니다. 유일한 금지 사용은 Webflow와 경쟁하는 비주얼 애니메이션 빌더 도구를 구축하는 것입니다. 모든 플러그인은 공개 패키지에 포함됩니다: ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools 등.
  • @gsap/[email protected]는 useGSAP를 제공합니다.
  • 새 프로젝트 전에 확인: npm view gsap version license 및 ls node_modules/gsap/*.js.
  • ScrollSmoother 또는 Lenis 중 하나만 사용하고, 둘 다 사용하지 마십시오. 이 스튜디오는 Lenis를 표준으로 사용합니다(lenis-scroll 스킬).

아키텍처 (assets/를 src/motion/에 복사)

파일역할
assets/registry.ts플러그인을 한 번 등록하고, 프로젝트의 CustomEases를 생성하며, 기본값을 설정하고, ScrollTrigger.config({ ignoreMobileResize: true })를 적용합니다. 모든 모듈은 여기에서 gsap을 가져옵니다.
assets/tokens.tsANIMATION_SPECIFICATION.md + prefersReducedMotion()에서 가져온 모션 토큰(지속 시간, 이징, 스태거)
assets/lit.ts예제 재사용 가능한 텍스트 프리미티브: aria:'auto', autoSplit, 트윈을 반환하는 onSplit이 포함된 SplitText. 브랜드에 맞게 리빌 방식을 조정하세요(리터럴, 마스크, 슬라이드 등).
assets/useReducedMotion.tsDOM 수준 전환을 위한 실시간 prefers-reduced-motion 훅 (예: 핀 대신 정적 단계 렌더링)
assets/examples/*.tsx참조 데모에서 검증된 패턴: 핀 스크러빙 시퀀스(Method), Flip 필터(ScheduleIndex), quickTo 기반 인터랙티브(TheHour), 한 번 리빌(Rooms), 경로 전환 베일(Router)

이 파일들은 이 저장소의 demo/에서 검증된 구현이며, Playwright 스위트(경로 간 정리, 축소 모션, 스크롤 동기화)에 의해 실행됩니다.

React에서 GSAP 버그의 90%를 방지하는 규칙

  1. 모든 애니메이션은 useGSAP(() => {...}, { scope: ref }) 내부에 있어야 합니다. 컨텍스트는 언마운트 시 모든 트윈, ScrollTrigger, SplitText 및 matchMedia 브랜치를 되돌립니다. 이벤트 핸들러 애니메이션은 contextSafe를 사용하세요.
  2. 모듈 스코프나 useEffect(되돌림 없이)에서 ScrollTrigger를 절대 생성하지 마십시오. 정리 전략으로 ScrollTrigger.killAll()을 호출하지 마십시오.
  3. 섹션당 하나의 gsap.matchMedia() 를 motion/reduce(및 데스크탑/모바일) 조건과 함께 사용하세요. 초기 숨김 상태는 모션 브랜치 내부에서 설정되므로, JS 비활성화 및 축소 모션 사용자는 최종 콘텐츠를 볼 수 있습니다.
  4. Strict Mode 안전: useGSAP는 React 18/19 이중 호출을 처리합니다. 누수 확인: ScrollTrigger.getAll().length가 경로 이동 후 기준값으로 돌아오는지 확인하세요.
  5. 레이아웃 변경 후 리프레시: 글꼴 로드 후(document.fonts.ready.then(() => ScrollTrigger.refresh())), 목록 필터링 후, 경로 콘텐츠 마운트 후. 레이아웃에서 계산된 트리거 값이 있는 경우 invalidateOnRefresh: true를 사용하세요.
  6. 핀 올바르게 사용: 내부 래퍼를 핀으로 지정하고, pinSpacing을 유지하며, 웹폰트에 의존하지 않는 min-height: 100svh를 제공하고, Lenis와 함께 anticipatePin: 1을 사용하세요. 경험당 하나의 핀을 사용하세요. 핀이 쌓이면 사용자가 혼란스러워합니다.
  7. 저렴한 속성만 애니메이션화: transform, opacity, clip-path; CSS 변수는 작은 서브트리에만 사용하세요. 스크러빙된 타임라인에서 width/height/top/left를 피하고, 쓰기 전에 레이아웃을 읽으세요(GSAP는 자체 쓰기를 배치 처리합니다).
  8. will-change는 애니메이션 중에만, 그리고 소수의 레이어에만 적용하세요.

레시피

references/recipes.md에는 테스트되거나 문서화된 패턴이 포함되어 있습니다: 시네마틱 히어로 시퀀스, SplitText 리빌(문자/단어/줄, 마스크), clip-path 및 마스크 전환, 핀 스크러빙 스토리텔링, 수평 스크롤 섹션(containerAnimation), 패럴랙스 레이어, Flip 상태 모프, Observer 기반 제스처 섹션, Draggable + Inertia 캐러셀, 마그네틱 버튼, 커서 팔로워, SVG 모프/드로우, WebGL로의 이미지 왜곡 핸드오프, 페이지 전환, WebGL 카메라를 이용한 3D 스크롤.

references/react-lifecycle.md는 경로 변경, 리사이즈, 콘텐츠 변경 및 디버깅 누수에 대해 다룹니다.

애니메이션 전 목적 있는 모션 체크리스트

  • 이 애니메이션이 전달하는 것은 무엇입니까(계층, 인과 관계, 상태, 브랜드 소재)? 없다면 삭제하세요.
  • 이것이 시그니처 순간입니까, 아니면 조용히 있어야 합니까?
  • 축소 모션 대신 무엇을 보여줍니까? (완전히 이해할 수 있어야 합니다.)
  • 모바일 표현은 무엇입니까? (호버 효과에는 터치 대안이 필요하고, 핀은 더 짧아집니다.)
  • 페이지가 생성하는 ScrollTrigger는 몇 개입니까? QA가 이를 확인할 수 있도록 사양에 인벤토리를 작성하세요.

관련 스킬