목표
Erlin 개인 사이트 애니메이션 방법론: Next.js/React 사이트에 motion 라이브러리 도입, framer-motion에서 마이그레이션, 스크롤 공개(Reveal) / 지연(stagger) 그리드 / 페이지 전환 / 내비게이션 애니메이션 구축, 그리고 절대로 애니메이션이 콘텐츠를 가리지 않도록 합니다. 핵심 교훈: whileInView가 이전에 홈페이지 프로젝트 카드를 opacity:0 상태로 고정시킨 사례가 있었습니다("프로젝트 카드가 사라졌습니다"). 따라서 가시성 폴백이 필요합니다; 이미 신뢰할 수 있는 구현은 유지할 수 있으며, Reveal은 선택적 참고 사항으로, whileInView를 전면 금지하지는 않습니다.
실행 단계
-
먼저 프로젝트 환경을 파악하세요 (작업 시작 전 30초 동안 확인하여 잘못된 템플릿 적용을 방지합니다):
- 패키지 매니저: 하나의 lockfile만 인정합니다:
pnpm-lock.yaml→ pnpm,package-lock.json→ npm,yarn.lock→ yarn,bun.lock또는bun.lockb→ bun. lockfile이 여러 개면 중지하고 사용자에게 문의하세요; lockfile이 없으면package.json의packageManager를 확인하고, 그래도 판단할 수 없으면 중지하며 패키지 매니저를 추측하지 않습니다. 이후 설치, 마이그레이션, lint, build 명령은 확인된 매니저를 따릅니다. - Next/React 버전: 실제 Next/React와 애니메이션 라이브러리 버전, peer dependencies, 공식 호환성 설명을 확인하고, 버전을 하드코딩하거나 크로스 버전 API 완전 호환을 주장하지 않습니다.
- 라우트 구조 (템플릿 적용 전에 먼저 탐색하며 App Router를 기본값으로 가정하지 않습니다):
app/디렉터리 있음 → App Router, 아래 규칙에 따라 템플릿 선택;pages/만 있음 → Pages Router,template.tsx메커니즘이 없으므로pages/_app.tsx또는 대상 페이지 컴포넌트 레벨에서 전환을 처리하고 사용자에게 차이점을 설명합니다; 둘 다 없음 → Next가 아닌 프로젝트로, 프레임워크의 자체 마운트 포인트에 동등하게 구현합니다. App Router: locale-접두사 라우트(app/[locale]/디렉터리)가 있는 경우 template은app/[locale]/template.tsx에 배치합니다; locale 라우트가 없는 경우 (예: 클라이언트 측 언어 전환)app/template.tsx에 배치하며, Next도 마찬가지로 모든 탐색에서 template을 다시 마운트하므로 fade-in이 정상 작동합니다. - 컴포넌트가 현재 server 컴포넌트인지 확인: 상호작용이 필요한 motion 요소는 최소한의 client 컴포넌트로 격리합니다; 서버 로직이 포함된 전체 컴포넌트를 그대로 client로 변경하지 마세요.
- 패키지 매니저: 하나의 lockfile만 인정합니다:
-
기존 종속성 유지: 이미
framer-motion이 있고 요구 사항을 충족한다면 계속 사용하고, 새 애니메이션을 추가한다고 기본적으로 마이그레이션하지 않습니다. 오직 사용자가 마이그레이션을 요청하거나 현재 기능/호환성상 꼭 필요할 때만 버전 차이를 확인한 후 프로젝트 패키지 매니저에 따라motion을 설치하고,motion/react임포트와 API를 모든 곳에서 확인합니다; 잔여 종속성이 없음을 확인한 후에만 이전 패키지를 제거합니다. 관련 없는 주석이나 문서는 덧붙여 수정하지 않습니다. -
애니메이션 적용: 필요에 따라 Reveal 참조: 템플릿은
assets/reveal.tsx에 있으며,components/motion/reveal.tsx로 복사하고 경로 별칭을 조정합니다. 설계 포인트 (프로젝트별로 조정):- 가시성 폴백: 템플릿은 IntersectionObserver + 2.5초 타임아웃을 사용합니다; 2.5초는 참조 매개변수일 뿐이며, 페이지와 로딩 동작에 따라 조정합니다. 검증된 whileInView 또는 다른 메커니즘을 사용하여 observer, JS, 또는 hydration 실패 시에도 콘텐츠에 접근 가능해야 합니다.
- SSR/hydration 및 프로젝트 lint 규칙에 따라 reduced-motion과 observer 부재를 처리합니다; hydration 불일치 및 불필요한 동기 effect 업데이트를 방지하고, 한 번의 lint 경험을 모든 API의 금지 규칙으로 여기지 않습니다.
- reduced motion은 최종 상태를 직접 렌더링합니다.
- 순수 CSS 전환(
cubic-bezier(0.22,1,0.36,1))을 사용하고, motion.div를 사용하지 않으며, 애니메이션 런타임 오버헤드가 0입니다. Reveal에는 자체 className prop이 있습니다:div인 카드(예:glass카드)는 클래스 이름을 직접 Reveal에 전달하여 중첩을 줄입니다;article/section등 의미 있는 요소는 Reveal로 한 번 감싸서 의미를 유지합니다.
-
적용 위치 및 지연 공식:
위치 방법 delay 카드 그리드 (홈페이지 여러 블록) 각 항목 Reveal로 감싸기Math.min(i * 0.08, 0.4), 긴 그리드 지연 방지 위해 상한 설정아티클 리스트 (writing, latest-writing) 각 행 Reveal로 감싸기i * 0.05~0.07, 긴 리스트 지연 방지 위해Math.min(i*0.05, 0.3)상한 설정프로젝트 큰 이미지 행의 텍스트 열 Reveal고정 0.15, 이미지 시차와 분리본문/연락처 카드 (about) 큰 블록 Reveal두 번째 블록 0.1내비게이션 바 motion.header초기y:"-100%"슬라이드 인, 스크롤 숨김은 동일한 transform 재사용— 모바일 메뉴 AnimatePresence+opacity/y전환,block/hidden전환 대체— 라우트 전환 새 app/template.tsx(locale 라우트 없음) 또는app/[locale]/template.tsx(locale-접두사; Next는 모든 탐색에서 template을 다시 마운트)에서opacity+yfade-in, 0.35초— -
검증 및 전달: 1단계에서 확인된 패키지 매니저에 따라:
pnpm lint && pnpm build # pnpm 프로젝트; build 반드시 성공 (전체 SSG 프로젝트는 SSG 내보내기 포함) npm run lint && npm run build # npm 프로젝트사용자가 커밋을 승인한 경우에만 프로젝트 커밋 관례에 따라, 예:
feat(motion): migrate motion library and add full-site animations. 이번 작업 관련 파일만 add하세요——리포지토리에 섞여 있는 관련 없는 미커밋 변경사항을 이번 커밋에 함께 포함시키지 마세요.
판단 규칙
- 사용 시기: Next.js 사이트에 새 애니메이션/모션 추가;
framer-motion을motion패키지로 마이그레이션 (마이그레이션 전에 현재 버전 API 확인); 사용자가 "스크롤 공개""지연""페이지 전환""더 많은 애니메이션" 요청. - 담당하지 않음: SwiftUI, CSS-only 또는 Remotion 영상 애니메이션.
- 애니메이션 설계 규칙 (문제 사례 정리):
- LCP 요소 (H1, hero)는 입장 애니메이션을 적용하지 않음:
SkewReveal에는instantprop이 있거나, 초기 상태를 최종 상태로 직접 설정해야 합니다. 그렇지 않으면 SSR 텍스트가 깜빡입니다. - 모든 애니메이션은
prefers-reduced-motion을 존중:useReducedMotion()을 사용하고, reduced일 때는 최종 상태를 렌더링/리스너를 등록하지 않습니다. - 통일된 easing
[0.22, 1, 0.36, 1](easeOutQuint 스타일), 지속 시간 0.3–0.8초, 절제가 우선. - 호버 애니메이션은 CSS transition으로 충분 (예:
hover:-translate-y-1,group-hover:scale-105), motion을 사용할 필요 없음. - 클라이언트 필터링 (예: 태그 필터) 시 key가 변경되지 않은 리스트 항목은 애니메이션을 다시 재생하지 않습니다——이는 예상된 동작이며, 새로 나타난 항목은 자동으로 트리거됩니다.
- LCP 요소 (H1, hero)는 입장 애니메이션을 적용하지 않음:
- 기존 컴포넌트 소속: SkewReveal 입장, Parallax 시차, Magnetic 마그넷, MouseParallax는 유지하고, 새 애니메이션은 같은 디렉터리에 공존합니다; 프로젝트에 이미
.zcode/.agents애니메이션 컴포넌트 디렉터리(예:components/motion/)가 있다면 새 컴포넌트는 같은 디렉터리에 배치합니다. - server/client 경계: 서버 컴포넌트는
Reveal을 직접 렌더링할 수 있습니다 (client 컴포넌트이지만 자식 컴포넌트로 사용하는 데 문제없습니다).
애니메이션 완료 전에 실제로 시각적 접근성 및 콘텐츠 가시성을 확인합니다; 본 스킬은 Next.js/React의 motion 구현 기술을 담당합니다; RN/Expo 또는 다른 스택의 애니메이션은 동일한 원칙으로 직접 구현하며, 이 스킬 스크립트에 의존하지 않습니다.
출력 형식
Reveal컴포넌트 배치:assets/reveal.tsx에서 복사하여components/motion/reveal.tsx에 배치하고 경로 별칭 조정.- 라우트 전환:
app/template.tsx(locale 라우트 없음) 또는app/[locale]/template.tsx(locale-접두사),opacity+yfade-in 0.35초. - 커밋 메시지: conventional commits + 한국어 설명, 예:
feat(motion): migrate motion library and add full-site animations.
예시
사용자 질문
"사이트에 스크롤 공개를 추가하고, framer-motion을 motion으로 바꿔주세요."
도구 반환
pnpm
pnpm add motion && pnpm remove framer-motion 성공, package.json에 호환되는 motion 버전이 나타났습니다; pnpm lint && pnpm build 전체 SSG가 계속 성공.
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <files> 실행 후, 모든 임포트가 motion/react를 가리킵니다; 이번 마이그레이션 관련 설명 중 실제로 만료된 것만 업데이트합니다.
최종 출력
components/motion/reveal.tsx (수동 IntersectionObserver + 2.5초 퓨즈) + 카드/리스트 지연 + app/template.tsx 라우트 fade-in; lint, build 통과; 실제 검증 보고; 커밋 권한이 있는 경우에만 이번 작업 관련 파일을 커밋합니다.
게이트
- 콘텐츠 한계선: 절대로 애니메이션이 콘텐츠를 가리지 않도록 합니다——SSR, reduced-motion, observer/스크립트 예외 시 콘텐츠 접근 가능 여부 확인; Reveal과 타임아웃 매개변수는 참조 구현이며, API를 기계적으로 비활성화하지 않습니다.
- 접근성 한계선: 모든 애니메이션은
prefers-reduced-motion을 존중; LCP 요소 (H1, hero)는 입장 애니메이션을 적용하지 않습니다. - 검증: 확인된 패키지 매니저로
lint && build실행,build는 반드시 성공해야 합니다 (프로젝트가 전체 SSG일 경우 SSG 내보내기도 손상되지 않아야 함; SSR/ISR 프로젝트는 build 통과를 기준으로 하며, SSG 요구 사항을 허위로 만들지 않습니다). - 커밋 규율: 이번 작업 관련 파일만 add하고, 리포지토리에 관련 없는 미커밋 변경사항을 함께 커밋하지 않습니다.
- 점진적 향상: 이미 작동 중인 애니메이션 컴포넌트를 "스타일 통일"을 위해 건드리지 말고, 요구 사항과 접근성 증거에 따라 판단합니다.