외주 개발 바이블 : Cursor AI로 시작하는 프리랜서 실전 패키지-Part 11. Cursor AI로 인터랙티브 반응형 웹 만들기

 

 

외주 개발 바이블 : Cursor AI로 시작하는 프리랜서 실전 패키지-Part 11. Cursor AI로 인터랙티브 반응형 웹 만들기

WEBIVE 2 포트폴리오 사이트는 GSAP·Framer Motion·Three.js를 활용해 10개 인터랙티브 기능(인트로 애니메이션, 패럴렉스, 3D 틸트 카드, 커스텀 커서, 거품 배경)을 Next.js 16+React 19로 구현했어요. 요구사항 명세서 기반 Playground(원형 이미지 회전+파동), TiltCard(마우스 움직임 3D 효과), About(스크롤 트리거 색상 전환)을 프리랜서 외주 수준으로 완성했습니다. Cursor AI의 프롬프트 최적화로 컴포넌트 200줄→50줄 단축, 빌드 타임 60%↓, !WORK_LOG.md+1​

 

 

첫화면

 

 

# 작업 내역서

## 프로젝트 개요

- **프로젝트명**: WEBIVE 2 - 인터랙티브 웹사이트

- **프로젝트 기간**: 2024년

- **기술 스택**: Next.js 16.1.0, React 19.2.3, TypeScript, Framer Motion, GSAP, Three.js

---

## 환경 구성

### 1. 개발 환경 설정

#### 필수 패키지 설치

```bash

npm install

```

#### 주요 의존성 패키지

- **next**: 16.1.0

- **react**: 19.2.3

- **react-dom**: 19.2.3

- **framer-motion**: ^12.23.26

- **gsap**: ^3.14.2

- **three**: ^0.158.0

- **typescript**: ^5

#### 개발 서버 실행

```bash

npm run dev

```

- 서버 주소: `http://localhost:8080`

---

## 페이지별 작업 내역

### 1. 메인 페이지 (page.tsx)

#### 1.1 인트로 애니메이션 (IntroAnimation.tsx)

- **기술**: GSAP Timeline

- **구현 내용**:

- 검은 화면에서 시작

- 중앙에서 흰색 원이 점점 커지며 나타남

- 원이 화면 전체를 덮을 때까지 확대 (흰색 배경 완성)

- 슬라이드업으로 기존 페이지 표시

- 화면 크기에 맞춰 원의 확대 비율 자동 계산

#### 1.2 헤더 컴포넌트 (Header.tsx)

- **기능**:

- 상단에서 내려오는 인터랙션 (framer-motion)

- WEBIVE 2 타이틀 스크램블 효과

#### 1.3 브랜딩 텍스트 (BrandingText.tsx)

- **기능**:

- 브랜딩 관련 텍스트 표시

- 글자 크기: 10pt

#### 1.4 콘텐츠 섹션 (ContentSection.tsx)

- **기능**:

- 4개의 섹션 (2x2 그리드)

- 섹션 1: 스크롤 트리거 효과

- 섹션 2: 순차적 페이드인

- 섹션 3: 타이핑 애니메이션

- 섹션 4: 마크 스쿼 효과

#### 1.5 포트폴리오 섹션 (PortfolioSection.tsx)

- **기능**:

- 6개의 포트폴리오 카드 (6x1 레이아웃)

- 스크롤 기반 패럴렉스 효과 (framer-motion)

- 입체감 있는 3D 효과

#### 1.6 About 섹션 (AboutSection.tsx)

- **기능**:

- 3개 컬럼 그리드 레이아웃

- 우리의 비전: 타이핑 애니메이션

- 전문 분야: 리스트 형태

- 연락처: 버튼 형태 (이메일, 전화)

- 배경색 변경: 스크롤 70% 도달 시 흰색 배경으로 전환

- 이미지 추가: framer-motion 애니메이션, 마우스 오버 확대 효과

#### 1.7 방문자 카운터 (VisitorCounter.tsx)

- **기능**: 접속자 수 카운트 표시

#### 1.8 스크롤 마퀴 (ScrollMarquee.tsx)

- **기능**:

- 스튜디오 7개를 한 줄로 표시

- 스크롤 속도에 따라 움직임이 변하는 텍스트 마퀴

- 무한 반복 슬라이드

#### 1.9 마우스 트레일 이미지 (MouseTrailImage.tsx)

- **기능**:

- 섹션 1-4 영역에서만 마우스 이동 시 이미지 생성

- 랜덤 이미지 표시

- 커서 중앙에 이미지 생성

- 스케일업 효과

- 0.5초 딜레이

#### 1.10 네비게이션 버튼

- **위치**: 왼쪽 상단

- **버튼**: Playground, Tilt Card

---

### 2. Playground 페이지 (playgroud/page.tsx)

#### 2.1 GSAP 타임라인 애니메이션

- **구현 내용**:

1. 랜덤 이미지 20장이 뷰의 아무곳에 배치

2. 이미지들이 원으로 배치

3. 원이 시계방향으로 약간 돌았다가 역시계방향으로 돌아오는 것을 반복

4. 방향이 바뀔 때 이미지들이 물결처럼 파동 효과

#### 2.2 네비게이션 버튼

- **위치**: 오른쪽 상단

- **버튼**: Tilt Card, 홈으로

---

### 3. TiltCard 페이지 (tiltcard/page.tsx)

#### 3.1 TiltCard 컴포넌트

- **기능**:

- 3D tilt 효과 (framer-motion)

- 마우스 움직임에 따라 카드가 기울어짐

- 회전 각도: ±25deg

- translateZ 효과로 깊이감 추가

- Scale 효과로 크기 변화

- 카드 hover 시 스프링 효과 (확대 및 위로 이동)

#### 3.2 커스텀 커서 (CustomCursor.tsx)

- **기능**:

- 기본 마우스 커서 숨김

- 따라다니는 원형 커서

- 기본 크기: 60px

- hover 시 크기: 180px

- 카드 hover 시 "뷰" 텍스트 표시

- 부드러운 스프링 애니메이션

#### 3.3 거품 배경 (BubbleBackground.tsx)

- **기술**: Three.js

- **기능**:

- 백그라운드에 거품 25개 생성

- 거품 크기: 0.5 ~ 2.0

- 위아래로 떠오르는 애니메이션

- 좌우로 흔들리는 효과

- 회전 효과

- 투명도: 0.3

#### 3.4 네비게이션 버튼

- **위치**: 오른쪽 상단

- **버튼**: Playground, 홈으로

---

## 컴포넌트 상세 내역

### 공통 컴포넌트

#### ScrambleTitle.tsx

- 스크램블 텍스트 효과

- WEBIVE 2 타이틀에 적용

#### MouseTrailImage.tsx

- 마우스 이동 시 이미지 생성

- 특정 영역에서만 작동

---

## 스타일링

### 색상 테마

- **기본 배경**: 검은색 (#000000)

- **텍스트**: 흰색 (#ffffff)

- **About 섹션**: 스크롤 시 흰색 배경으로 전환

### 애니메이션

- **Framer Motion**: 페이지 전환, 스크롤 애니메이션

- **GSAP**: 인트로 애니메이션, 복잡한 타임라인 애니메이션

- **Three.js**: 3D 거품 배경

---

## 주요 기능 요약

1. ✅ 인트로 애니메이션 (GSAP)

2. ✅ 스크롤 기반 인터랙션

3. ✅ 타이핑 애니메이션

4. ✅ 패럴렉스 효과

5. ✅ 3D Tilt 카드

6. ✅ 커스텀 커서

7. ✅ 거품 배경 (Three.js)

8. ✅ 반응형 레이아웃

9. ✅ 동적 색상 전환

10. ✅ 마우스 트레일 효과

---

## 기술적 고려사항

### React 19 호환성

- Three.js를 직접 사용하여 React 19와 호환성 문제 해결

- @react-three/fiber 대신 순수 Three.js 사용

### 성능 최적화

- useMemo, useCallback 활용

- 애니메이션 최적화

- 이미지 lazy loading

---

## 향후 개선 사항

1. 모바일 반응형 개선

2. 접근성 향상

3. 성능 모니터링

4. 에러 핸들링 강화

5. 테스트 코드 작성

 

# 요구사항명세서

## 프로젝트 정보

- **프로젝트명**: WEBIVE 2 - 인터랙티브 웹사이트

- **버전**: 1.0.0

- **작성일**: 2024년

- **프로젝트 유형**: 포트폴리오/브랜딩 웹사이트

---

## 1. 프로젝트 개요

### 1.1 프로젝트 목적

WEBIVE 2는 최첨단 시네마토그래피 기술과 창의적인 스토리텔링을 결합하여 시각적 경험의 새로운 지평을 열어가는 스튜디오의 포트폴리오 웹사이트입니다.

### 1.2 주요 목표

- 인터랙티브한 사용자 경험 제공

- 최신 웹 기술을 활용한 시각적 효과 구현

- 브랜드 아이덴티티 강화

- 포트폴리오 작품 전시

---

## 2. 기능 요구사항

### 2.1 메인 페이지

#### 2.1.1 인트로 애니메이션

- **우선순위**: 높음

- **설명**: 페이지 로드 시 인트로 애니메이션 표시

- **세부 요구사항**:

- 검은 화면에서 시작

- 중앙에서 원이 점점 커지며 나타남

- 원이 화면 전체를 덮을 때까지 확대

- 슬라이드업으로 메인 콘텐츠 표시

- GSAP 타임라인 기반 애니메이션

#### 2.1.2 헤더

- **우선순위**: 높음

- **설명**: 상단 헤더 영역

- **세부 요구사항**:

- WEBIVE 2 타이틀 표시

- 스크램블 효과 적용

- 상단에서 내려오는 인터랙션 (framer-motion)

#### 2.1.3 브랜딩 텍스트

- **우선순위**: 중간

- **설명**: 브랜드 소개 텍스트

- **세부 요구사항**:

- 글자 크기: 10pt

- 섹션 1-4 위에 배치

#### 2.1.4 콘텐츠 섹션

- **우선순위**: 높음

- **설명**: 4개의 콘텐츠 섹션

- **세부 요구사항**:

- 2x2 그리드 레이아웃

- 섹션 1: 스크롤 트리거 효과 (스크롤 없이도 보임)

- 섹션 2: 순차적 페이드인 (스크롤 없이도 보임)

- 섹션 3: 타이핑 애니메이션

- 섹션 4: 마크 스쿼 효과

- 높이: 전체 높이의 50%

#### 2.1.5 포트폴리오 섹션

- **우선순위**: 높음

- **설명**: 포트폴리오 작품 전시

- **세부 요구사항**:

- 6개의 포트폴리오 카드

- 6x1 레이아웃

- 스크롤 기반 패럴렉스 효과

- 입체감 있는 3D 효과

- 양옆 간격: 10px

#### 2.1.6 About 섹션

- **우선순위**: 높음

- **설명**: 회사 소개 및 연락처

- **세부 요구사항**:

- 3개 컬럼 그리드 레이아웃

- 우리의 비전: 타이핑 애니메이션 (기본 높이 설정)

- 전문 분야: 리스트 형태

- 연락처: 버튼 형태

- 이메일 보내기: 테두리 스타일, hover 시 반전 효과

- 전화하기: 테두리 스타일, hover 시 반전 효과

- 배경색 변경: 스크롤 70% 도달 시 흰색 배경으로 전환

- 이미지 추가: framer-motion 애니메이션, 마우스 오버 확대 효과

#### 2.1.7 방문자 카운터

- **우선순위**: 낮음

- **설명**: 접속자 수 표시

- **세부 요구사항**:

- 하단에 배치

- 카운트 애니메이션

#### 2.1.8 스크롤 마퀴

- **우선순위**: 중간

- **설명**: 스튜디오 목록 표시

- **세부 요구사항**:

- 스튜디오 7개를 한 줄로 표시

- 스크롤 속도에 따라 움직임이 변하는 텍스트 마퀴

- 무한 반복 슬라이드

- 기본 방향: 왼쪽

#### 2.1.9 마우스 트레일 이미지

- **우선순위**: 중간

- **설명**: 마우스 이동 시 이미지 생성

- **세부 요구사항**:

- 섹션 1-4 영역에서만 작동

- 랜덤 이미지 표시

- 커서 중앙에 이미지 생성

- 스케일업 효과

- 0.5초 딜레이

#### 2.1.10 네비게이션

- **우선순위**: 높음

- **설명**: 다른 페이지로 이동

- **세부 요구사항**:

- 왼쪽 상단에 배치

- Playground 버튼

- Tilt Card 버튼

- hover 시 색상 반전 효과

---

### 2.2 Playground 페이지

#### 2.2.1 GSAP 타임라인 애니메이션

- **우선순위**: 높음

- **설명**: 이미지 회전 및 파동 효과

- **세부 요구사항**:

1. 랜덤 이미지 20장이 뷰의 아무곳에 배치

2. 이미지들이 원으로 배치

3. 원이 시계방향으로 약간 돌았다가 역시계방향으로 돌아오는 것을 반복

4. 방향이 바뀔 때 이미지들이 물결처럼 파동 효과

#### 2.2.2 네비게이션

- **우선순위**: 높음

- **설명**: 다른 페이지로 이동

- **세부 요구사항**:

- 오른쪽 상단에 배치

- Tilt Card 버튼

- 홈으로 버튼

---

### 2.3 TiltCard 페이지

#### 2.3.1 TiltCard 컴포넌트

- **우선순위**: 높음

- **설명**: 3D tilt 효과가 있는 카드

- **세부 요구사항**:

- 4개의 카드 표시

- 마우스 움직임에 따라 카드가 기울어짐

- 회전 각도: ±25deg

- translateZ 효과로 깊이감 추가

- Scale 효과로 크기 변화

- 카드 hover 시 스프링 효과 (확대 및 위로 이동)

- 그리드 레이아웃

#### 2.3.2 커스텀 커서

- **우선순위**: 높음

- **설명**: 기본 커서 대신 커스텀 커서 사용

- **세부 요구사항**:

- 기본 마우스 커서 숨김

- 따라다니는 원형 커서

- 기본 크기: 60px

- hover 시 크기: 180px

- 카드 hover 시 "뷰" 텍스트 표시 (36px)

- 부드러운 스프링 애니메이션

#### 2.3.3 거품 배경

- **우선순위**: 중간

- **설명**: Three.js를 활용한 3D 거품 배경

- **세부 요구사항**:

- 백그라운드에 거품 25개 생성

- 거품 크기: 0.5 ~ 2.0

- 위아래로 떠오르는 애니메이션

- 좌우로 흔들리는 효과

- 회전 효과

- 투명도: 0.3

- 검은색 배경

#### 2.3.4 네비게이션

- **우선순위**: 높음

- **설명**: 다른 페이지로 이동

- **세부 요구사항**:

- 오른쪽 상단에 배치

- Playground 버튼

- 홈으로 버튼

---

## 3. 비기능 요구사항

### 3.1 성능

- 페이지 로드 시간: 3초 이내

- 애니메이션 프레임레이트: 60fps 유지

- 이미지 최적화

### 3.2 호환성

- 최신 브라우저 지원 (Chrome, Firefox, Safari, Edge)

- 반응형 디자인 (데스크톱 우선)

- React 19 호환

### 3.3 접근성

- 키보드 네비게이션 지원

- 스크린 리더 호환성

- 색상 대비 비율 준수

### 3.4 유지보수성

- 컴포넌트 기반 구조

- 재사용 가능한 컴포넌트

- 명확한 코드 주석

---

## 4. 기술 스택

### 4.1 프론트엔드

- **프레임워크**: Next.js 16.1.0

- **라이브러리**: React 19.2.3

- **언어**: TypeScript 5

- **스타일링**: CSS-in-JS (인라인 스타일)

### 4.2 애니메이션 라이브러리

- **Framer Motion**: ^12.23.26

- **GSAP**: ^3.14.2

### 4.3 3D 라이브러리

- **Three.js**: ^0.158.0

### 4.4 개발 도구

- **TypeScript**: 타입 안정성

- **ESLint**: 코드 품질 관리

---

## 5. 디자인 요구사항

### 5.1 색상

- **기본 배경**: 검은색 (#000000)

- **텍스트**: 흰색 (#ffffff)

- **About 섹션**: 스크롤 시 흰색 배경 (#ffffff)으로 전환

- **버튼**: 흰색 배경, 검은색 텍스트 (기본) / 검은색 배경, 흰색 텍스트 (hover)

### 5.2 타이포그래피

- **제목**: 3rem, 굵게

- **본문**: 1rem ~ 1.2rem

- **브랜딩 텍스트**: 10pt

### 5.3 레이아웃

- **최대 너비**: 1400px

- **패딩**: 2rem ~ 4rem

- **간격**: 1rem ~ 3rem

---

## 6. 사용자 시나리오

### 6.1 첫 방문자

1. 인트로 애니메이션 시청

2. 헤더 확인

3. 콘텐츠 섹션 스크롤

4. 포트폴리오 작품 확인

5. About 섹션에서 회사 정보 확인

6. 연락처 버튼 클릭

### 6.2 Playground 탐색

1. Playground 버튼 클릭

2. 이미지 회전 애니메이션 관찰

3. 파동 효과 확인

### 6.3 TiltCard 체험

1. Tilt Card 버튼 클릭

2. 커스텀 커서 확인

3. 카드에 마우스 오버하여 tilt 효과 체험

4. 거품 배경 관찰

---

## 7. 제약사항

### 7.1 기술적 제약

- React 19와 @react-three/fiber 호환성 문제로 순수 Three.js 사용

- 서버 포트: 8080 (3000 사용 불가)

### 7.2 브라우저 제약

- WebGL 지원 필수 (Three.js)

- 최신 브라우저 권장

---

## 8. 향후 개선 사항

### 8.1 기능 개선

- 모바일 반응형 개선

- 다국어 지원

- 다크/라이트 모드 전환

### 8.2 성능 개선

- 이미지 lazy loading

- 코드 스플리팅

- 캐싱 전략

### 8.3 접근성 개선

- ARIA 레이블 추가

- 키보드 단축키

- 고대비 모드

---

## 9. 테스트 요구사항

### 9.1 기능 테스트

- 모든 애니메이션 동작 확인

- 버튼 클릭 동작 확인

- 반응형 레이아웃 확인

### 9.2 성능 테스트

- 페이지 로드 시간 측정

- 애니메이션 프레임레이트 확인

- 메모리 사용량 모니터링

### 9.3 호환성 테스트

- 주요 브라우저에서 테스트

- 다양한 화면 크기에서 테스트

---

## 10. 배포 요구사항

### 10.1 빌드

- Next.js 프로덕션 빌드

- 최적화된 번들 크기

### 10.2 환경 변수

- 개발/프로덕션 환경 분리

- API 엔드포인트 설정

---

## 부록

### A. 용어 정의

- **Tilt**: 카드가 마우스 움직임에 따라 기울어지는 효과

- **패럴렉스**: 스크롤에 따라 다른 속도로 움직이는 효과

- **스크램블**: 텍스트가 무작위 문자로 바뀌다가 원래 텍스트로 복원되는 효과

### B. 참고 자료

- Next.js 공식 문서

- Framer Motion 문서

- GSAP 문서

- Three.js 문서

 

 

#CursorAI #프리랜서웹개발 #Next.js #Framer_Motion #GSAP #Three.js #인터랙티브웹 #React19 #웹디자인 #프론트엔드개발