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.ts | ANIMATION_SPECIFICATION.md + prefersReducedMotion()에서 가져온 모션 토큰(지속 시간, 이징, 스태거) |
assets/lit.ts | 예제 재사용 가능한 텍스트 프리미티브: aria:'auto', autoSplit, 트윈을 반환하는 onSplit이 포함된 SplitText. 브랜드에 맞게 리빌 방식을 조정하세요(리터럴, 마스크, 슬라이드 등). |
assets/useReducedMotion.ts | DOM 수준 전환을 위한 실시간 prefers-reduced-motion 훅 (예: 핀 대신 정적 단계 렌더링) |
assets/examples/*.tsx | 참조 데모에서 검증된 패턴: 핀 스크러빙 시퀀스(Method), Flip 필터(ScheduleIndex), quickTo 기반 인터랙티브(TheHour), 한 번 리빌(Rooms), 경로 전환 베일(Router) |
이 파일들은 이 저장소의 demo/에서 검증된 구현이며, Playwright 스위트(경로 간 정리, 축소 모션, 스크롤 동기화)에 의해 실행됩니다.
React에서 GSAP 버그의 90%를 방지하는 규칙
- 모든 애니메이션은
useGSAP(() => {...}, { scope: ref })내부에 있어야 합니다. 컨텍스트는 언마운트 시 모든 트윈, ScrollTrigger, SplitText 및 matchMedia 브랜치를 되돌립니다. 이벤트 핸들러 애니메이션은contextSafe를 사용하세요. - 모듈 스코프나
useEffect(되돌림 없이)에서 ScrollTrigger를 절대 생성하지 마십시오. 정리 전략으로ScrollTrigger.killAll()을 호출하지 마십시오. - 섹션당 하나의
gsap.matchMedia()를motion/reduce(및 데스크탑/모바일) 조건과 함께 사용하세요. 초기 숨김 상태는 모션 브랜치 내부에서 설정되므로, JS 비활성화 및 축소 모션 사용자는 최종 콘텐츠를 볼 수 있습니다. - Strict Mode 안전:
useGSAP는 React 18/19 이중 호출을 처리합니다. 누수 확인:ScrollTrigger.getAll().length가 경로 이동 후 기준값으로 돌아오는지 확인하세요. - 레이아웃 변경 후 리프레시: 글꼴 로드 후(
document.fonts.ready.then(() => ScrollTrigger.refresh())), 목록 필터링 후, 경로 콘텐츠 마운트 후. 레이아웃에서 계산된 트리거 값이 있는 경우invalidateOnRefresh: true를 사용하세요. - 핀 올바르게 사용: 내부 래퍼를 핀으로 지정하고,
pinSpacing을 유지하며, 웹폰트에 의존하지 않는min-height: 100svh를 제공하고, Lenis와 함께anticipatePin: 1을 사용하세요. 경험당 하나의 핀을 사용하세요. 핀이 쌓이면 사용자가 혼란스러워합니다. - 저렴한 속성만 애니메이션화: transform, opacity, clip-path; CSS 변수는 작은 서브트리에만 사용하세요. 스크러빙된 타임라인에서 width/height/top/left를 피하고, 쓰기 전에 레이아웃을 읽으세요(GSAP는 자체 쓰기를 배치 처리합니다).
will-change는 애니메이션 중에만, 그리고 소수의 레이어에만 적용하세요.
레시피
references/recipes.md에는 테스트되거나 문서화된 패턴이 포함되어 있습니다: 시네마틱 히어로 시퀀스, SplitText 리빌(문자/단어/줄, 마스크), clip-path 및 마스크 전환, 핀 스크러빙 스토리텔링, 수평 스크롤 섹션(containerAnimation), 패럴랙스 레이어, Flip 상태 모프, Observer 기반 제스처 섹션, Draggable + Inertia 캐러셀, 마그네틱 버튼, 커서 팔로워, SVG 모프/드로우, WebGL로의 이미지 왜곡 핸드오프, 페이지 전환, WebGL 카메라를 이용한 3D 스크롤.
references/react-lifecycle.md는 경로 변경, 리사이즈, 콘텐츠 변경 및 디버깅 누수에 대해 다룹니다.
애니메이션 전 목적 있는 모션 체크리스트
- 이 애니메이션이 전달하는 것은 무엇입니까(계층, 인과 관계, 상태, 브랜드 소재)? 없다면 삭제하세요.
- 이것이 시그니처 순간입니까, 아니면 조용히 있어야 합니까?
- 축소 모션 대신 무엇을 보여줍니까? (완전히 이해할 수 있어야 합니다.)
- 모바일 표현은 무엇입니까? (호버 효과에는 터치 대안이 필요하고, 핀은 더 짧아집니다.)
- 페이지가 생성하는 ScrollTrigger는 몇 개입니까? QA가 이를 확인할 수 있도록 사양에 인벤토리를 작성하세요.