sam-react-prod/claudedocs/guides/[REF] mobile-zoom-fix-guide.md

모바일 핀치 줌(Pinch Zoom) 이슈 해결 가이드

작성일: 2026-01-15 상태: 해결 완료 적용 범위: iOS Safari, Android Chrome

---

1. 문제 현상

1-1. 초기 증상

• 모바일에서 핀치 줌(손가락 확대)이 특정 화면에서만 동작
• 확대 시 아래에서 회색/어두운 영역이 올라와 화면을 가림
• Android / iOS 모두 동일한 현상

1-2. 영향 범위

화면	줌 가능	회색 영역
로그인 페이지	✅ 정상	❌ 없음
인증된 내부 페이지	❌ 불가 → ✅ 수정 후 가능	✅ 발생 → ❌ 수정 후 해결

---

2. 원인 분석

2-1. 핀치 줌 차단 원인

파일: src/layouts/AuthenticatedLayout.tsx

// 문제 코드 - touch-pan-y가 핀치 줌 차단
<main className="... touch-pan-y" style={{ WebkitOverflowScrolling: 'touch' }}>

touch-action 값	세로 스크롤	핀치 줌
pan-y	✅	❌ 차단
pan-y pinch-zoom	✅	✅
manipulation	✅	❌ 더블탭만

2-2. 회색 영역 발생 원인

원인 1: body에 추가된 safe-area 패딩

/* globals.css - 문제 코드 */
body {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}

• 확대 시 body가 확장되면서 패딩 영역이 화면에 노출

원인 2: 모바일 레이아웃 wrapper에 배경색 미지정

// 문제 코드 - 배경색 없음
<div className="flex flex-col overflow-hidden" style={{ height: 'var(--app-height)' }}>

• 배경색이 없어서 확대 시 뒤에 있는 요소(어두운 배경)가 투과되어 보임

원인 3: overflow-hidden으로 인한 콘텐츠 클리핑

• 고정 높이 + overflow-hidden = 확대 시 콘텐츠가 잘림

---

3. 해결 방법

3-1. 핀치 줌 활성화

파일: src/layouts/AuthenticatedLayout.tsx (Line 615)

// 변경 전
<main className="flex-1 overflow-y-auto px-3 overscroll-contain touch-pan-y"
      style={{ WebkitOverflowScrolling: 'touch' }}>

// 변경 후
<main className="flex-1 overflow-y-auto px-3 overscroll-contain"
      style={{ WebkitOverflowScrolling: 'touch', touchAction: 'pan-y pinch-zoom' }}>

3-2. body 패딩 제거

파일: src/app/globals.css

/* 변경 전 */
body {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}

/* 변경 후 - 해당 코드 제거 */
/* safe-area 변수는 유지, body 패딩만 제거 */
:root {
  --safe-area-inset-top: env(safe-area-inset-top, 0px);
  --safe-area-inset-right: env(safe-area-inset-right, 0px);
  --safe-area-inset-bottom: env(safe-area-inset-bottom, 0px);
  --safe-area-inset-left: env(safe-area-inset-left, 0px);
}

3-3. 모바일 레이아웃 배경색 및 높이 수정

파일: src/layouts/AuthenticatedLayout.tsx (Line 370)

// 변경 전
<div className="flex flex-col overflow-hidden" style={{ height: 'var(--app-height)' }}>

// 변경 후
<div className="flex flex-col bg-background min-h-screen" style={{ height: 'var(--app-height)' }}>

변경 항목	효과
bg-background	배경색 명시적 지정 → 어두운 영역 가림
min-h-screen	최소 높이 보장 → 확대 시에도 배경 커버
overflow-hidden 제거	확대 시 콘텐츠 클리핑 방지

---

4. Viewport 설정 (참고)

파일: src/app/[locale]/layout.tsx

// 현재 설정 - 줌 허용 + iOS safe-area 지원
export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  minimumScale: 1,        // 최소 100%
  maximumScale: 5,        // 최대 500%까지 확대 가능
  userScalable: true,     // 손가락 확대 허용
  viewportFit: 'cover',   // 아이폰 노치/다이나믹 아일랜드/하단 홈바 영역 커버
};

---

5. 최종 변경 파일 목록

파일	변경 내용
src/layouts/AuthenticatedLayout.tsx	touch-action 수정, 배경색/높이 추가
src/app/globals.css	body padding-bottom 제거
src/app/[locale]/layout.tsx	viewport 설정 (이전에 적용됨)

---

6. 테스트 체크리스트

• iOS Safari 핀치 줌 동작
• Android Chrome 핀치 줌 동작
• 확대 시 회색 영역 미노출
• 로그인 페이지 정상 동작
• 내부 페이지(AuthenticatedLayout) 정상 동작
• 세로 스크롤 정상 동작

---

7. 관련 문서

• [REF] mobile-zoom-prevention-guide.md - 줌 방지가 필요할 때 적용 가이드

---

변경 이력

날짜	내용
2026-01-15	문서 작성, 이슈 해결 완료