Communitygithub.com

erlinerd/erlin-skills

Next.js/React 사이트에 motion 라이브러리를 도입하고, framer-motion에서 마이그레이션하며, 스크롤 공개(Reveal), 지연(stagger) 그리드, 페이지 전환, 내비게이션 애니메이션을 구축합니다. SwiftUI, CSS-only 또는 Remotion 영상 애니메이션은 담당하지 않습니다.

erlin-skills란 무엇인가요?

이 스킬은 Next.js/React 애플리케이션에 motion 라이브러리를 도입하고 framer-motion에서 마이그레이션하는 전문 기술입니다. 핵심 동작 방법론은 '애니메이션이 콘텐츠를 가리지 않도록 하는 것'이며, `whileInView`로 인해 프로젝트 카드가 `opacity:0` 상태에 갇히는 문제를 방지하기 위해 가시성 폴백(fallback)을 제공합니다. 주요 기능으로는 IntersectionObserver 기반의 `Reveal` 컴포넌트(2.5초 타임아웃), 카드 그리드와 아티클 리스트를 위한 지연(stagger) 공식(`Math.min(i * 0.08, 0.4)` 등), 라우트 전환(`app/template.tsx`), 내비게이션 메뉴 애니메이션이 포함됩니다. 모든 애니메이션은 `prefers-reduced-motion`을 존중하며, LCP 요소(H1, 히어로)는 입장 애니메이션을 적용하지 않습니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 에이전트 환경에서 활용하도록 설계되었으며, 프로젝트의 패키지 매니저(pnpm, npm, yarn, bun)와 라우터 구조(App Router/Pages Router)를 자동 감지하고, 서버/클라이언트 컴포넌트 경계를 유지하면서 motion을 점진적으로 도입합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

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

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

문서

목표

Erlin 개인 사이트 애니메이션 방법론: Next.js/React 사이트에 motion 라이브러리 도입, framer-motion에서 마이그레이션, 스크롤 공개(Reveal) / 지연(stagger) 그리드 / 페이지 전환 / 내비게이션 애니메이션 구축, 그리고 절대로 애니메이션이 콘텐츠를 가리지 않도록 합니다. 핵심 교훈: whileInView가 이전에 홈페이지 프로젝트 카드를 opacity:0 상태로 고정시킨 사례가 있었습니다("프로젝트 카드가 사라졌습니다"). 따라서 가시성 폴백이 필요합니다; 이미 신뢰할 수 있는 구현은 유지할 수 있으며, Reveal은 선택적 참고 사항으로, whileInView를 전면 금지하지는 않습니다.

실행 단계

  1. 먼저 프로젝트 환경을 파악하세요 (작업 시작 전 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로 변경하지 마세요.
  2. 기존 종속성 유지: 이미 framer-motion이 있고 요구 사항을 충족한다면 계속 사용하고, 새 애니메이션을 추가한다고 기본적으로 마이그레이션하지 않습니다. 오직 사용자가 마이그레이션을 요청하거나 현재 기능/호환성상 꼭 필요할 때만 버전 차이를 확인한 후 프로젝트 패키지 매니저에 따라 motion을 설치하고, motion/react 임포트와 API를 모든 곳에서 확인합니다; 잔여 종속성이 없음을 확인한 후에만 이전 패키지를 제거합니다. 관련 없는 주석이나 문서는 덧붙여 수정하지 않습니다.

  3. 애니메이션 적용: 필요에 따라 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로 한 번 감싸서 의미를 유지합니다.
  4. 적용 위치 및 지연 공식:

    위치방법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+y fade-in, 0.35초—
  5. 검증 및 전달: 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에는 instant prop이 있거나, 초기 상태를 최종 상태로 직접 설정해야 합니다. 그렇지 않으면 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가 변경되지 않은 리스트 항목은 애니메이션을 다시 재생하지 않습니다——이는 예상된 동작이며, 새로 나타난 항목은 자동으로 트리거됩니다.
  • 기존 컴포넌트 소속: 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+y fade-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하고, 리포지토리에 관련 없는 미커밋 변경사항을 함께 커밋하지 않습니다.
  • 점진적 향상: 이미 작동 중인 애니메이션 컴포넌트를 "스타일 통일"을 위해 건드리지 말고, 요구 사항과 접근성 증거에 따라 판단합니다.

관련 스킬