배경
프로덕트 화면에 다크모드 기능 요청.
현재 코드 확인 기준으로 bottle-note-frontend는 Tailwind의 class 기반 dark mode 설정과 CSS 변수 기반 토큰 일부가 이미 존재하지만, 실제 앱 루트/프로덕트 레이아웃에는 dark class 적용·사용자 설정·전환 UI가 아직 연결되어 있지 않은 상태로 보인다.
코드 확인 근거
tailwind.config.ts
darkMode: ['class'] 설정이 이미 있음background, foreground, card, border 등 CSS 변수 기반 색상 토큰이 일부 정의되어 있음
src/style/globals.css
:root와 .dark 색상 CSS 변수가 이미 존재함
src/app/layout.tsx
<html lang="ko" className="touch-manipulation">로 고정되어 있고, 테마 상태에 따른 dark class 주입은 없음- 루트 래퍼가
bg-bgGray 등 고정 색상 사용
src/app/(primary)/layout.tsx
- 프로덕트 기본 레이아웃이
bg-white로 고정되어 있음
src/store/settingsStore.ts
- Zustand persist 기반 설정 저장 구조가 이미 있으나, 현재는
currentScreen만 저장함
src/app/(primary)/settings/*
- 설정 화면과 메뉴 구조가 있어 다크모드 토글 진입점을 추가하기 적합함
요구 사항
프로덕트 화면에서 사용자가 라이트/다크 모드를 선택하거나 시스템 설정을 따를 수 있도록 한다.
권장 사용자 옵션
최소 범위로 시작할 경우 1차는 라이트/다크 토글만 제공하고, 이후 시스템 설정 추종을 확장해도 된다.
가능한 접근 방법
접근 A. 기존 구조 활용: Zustand persist + html class 제어
settingsStore 또는 별도 themeStore에 themeMode 저장
- 클라이언트 Provider에서 저장된 설정을 읽어
document.documentElement.classList.toggle('dark', ...) 적용
prefers-color-scheme은 system 모드일 때만 구독- 설정 화면에 다크모드 메뉴/토글 추가
장점:
- 기존 Zustand persist 패턴과 잘 맞음
- 신규 의존성 없이 구현 가능
- 현재 Tailwind
darkMode: ['class'] 설정을 그대로 활용 가능
주의점:
- 초기 렌더링 시 테마 class 적용 전 깜빡임이 생길 수 있어, 필요하면
<head>에 초기 테마 적용 스크립트 또는 provider 초기화 전략 필요
- 기존 화면에
bg-white, text-mainBlack, bg-bgGray처럼 고정 색상이 많아 일괄 치환/보정 필요
접근 B. next-themes 도입
next-themes로 SSR/CSR 테마 class 관리- 설정 화면에서
setTheme 호출
장점:
- Next.js 테마 class/시스템 설정 처리에 익숙한 패턴
- 초기 깜빡임 대응이 상대적으로 쉬움
주의점:
- 신규 의존성 도입이므로 번들 영향/유지보수성 검토와 승인 필요
- 현재 프로젝트 지침상 신규 패키지는 승인 후 설치해야 함
접근 C. 디자인 토큰 단계적 전환
- 먼저 글로벌 토큰과 레이아웃만 다크 대응
- 이후 주요 화면별로 고정 색상 클래스를
bg-background, text-foreground, bg-card, border-border 또는 보틀노트 전용 semantic token으로 단계적 치환
장점:
- 리스크를 낮추고 화면별 QA 가능
- 기존 디자인 시스템 정비와 함께 진행 가능
주의점:
- 화면별 색상 누락이 생기기 쉬워 QA 체크리스트가 필요
권장 구현 방향
1차 구현은 접근 A + C를 권장한다.
- 신규 의존성 없이 기존 Tailwind/Zustand 구조를 활용
settingsStore 또는 themeStore에 테마 설정 추가Providers 하위에 ThemeInitializer/ThemeProvider 추가html.dark class를 적용해 기존 .dark CSS 변수 사용- 프로덕트 공통 레이아웃부터
bg-white/bg-bgGray 고정값을 semantic token으로 변경
- 설정 화면에 다크모드 선택 UI 추가
- 주요 화면을 우선순위로 단계 대응
우선 적용 화면 제안
- 홈/탭바/공통 레이아웃
- 검색/상세
- 리뷰 목록/리뷰 상세
- 마이페이지/설정
- 로그인/커스텀 화면은 별도 디자인 의도가 있을 수 있어 후순위 검토
QA 체크리스트
- 앱 최초 진입 시 저장된 테마가 적용되는지
- 설정 화면에서 라이트/다크 전환 시 즉시 반영되는지
- 새로고침/재방문 후 설정이 유지되는지
- 시스템 설정 추종을 지원하는 경우 OS 테마 변경에 반응하는지
- 주요 화면의 배경/텍스트/카드/보더 대비가 충분한지
- 하단 탭바, 모달, 드로어, 토스트/알럿 등 공통 컴포넌트가 깨지지 않는지
- SVG/이미지 아이콘 중 darkgray/black 고정 아이콘이 다크 배경에서 보이는지
- WebView 환경에서 safe-area 배경색과 본문 배경색이 어긋나지 않는지
후속 검토 필요
- 다크모드 디자인 토큰을 Figma/디자인 시스템에서 별도 확정할지
- 브랜드 코랄 색상은 다크모드에서도 유지할지, 대비 보정 토큰을 둘지
- 설정값을 로컬 저장만 할지, 로그인 사용자 기준 서버 저장까지 확장할지
- 앱 WebView 네이티브 영역 상태바/하단 영역 색상 연동이 필요한지
배경
프로덕트 화면에 다크모드 기능 요청.
현재 코드 확인 기준으로
bottle-note-frontend는 Tailwind의 class 기반 dark mode 설정과 CSS 변수 기반 토큰 일부가 이미 존재하지만, 실제 앱 루트/프로덕트 레이아웃에는 dark class 적용·사용자 설정·전환 UI가 아직 연결되어 있지 않은 상태로 보인다.코드 확인 근거
tailwind.config.tsdarkMode: ['class']설정이 이미 있음background,foreground,card,border등 CSS 변수 기반 색상 토큰이 일부 정의되어 있음src/style/globals.css:root와.dark색상 CSS 변수가 이미 존재함src/app/layout.tsx<html lang="ko" className="touch-manipulation">로 고정되어 있고, 테마 상태에 따른darkclass 주입은 없음bg-bgGray등 고정 색상 사용src/app/(primary)/layout.tsxbg-white로 고정되어 있음src/store/settingsStore.tscurrentScreen만 저장함src/app/(primary)/settings/*요구 사항
프로덕트 화면에서 사용자가 라이트/다크 모드를 선택하거나 시스템 설정을 따를 수 있도록 한다.
권장 사용자 옵션
최소 범위로 시작할 경우 1차는
라이트/다크 토글만 제공하고, 이후 시스템 설정 추종을 확장해도 된다.가능한 접근 방법
접근 A. 기존 구조 활용: Zustand persist + html class 제어
settingsStore또는 별도themeStore에themeMode저장light | dark | systemdocument.documentElement.classList.toggle('dark', ...)적용prefers-color-scheme은system모드일 때만 구독장점:
darkMode: ['class']설정을 그대로 활용 가능주의점:
<head>에 초기 테마 적용 스크립트 또는 provider 초기화 전략 필요bg-white,text-mainBlack,bg-bgGray처럼 고정 색상이 많아 일괄 치환/보정 필요접근 B.
next-themes도입next-themes로 SSR/CSR 테마 class 관리setTheme호출장점:
주의점:
접근 C. 디자인 토큰 단계적 전환
bg-background,text-foreground,bg-card,border-border또는 보틀노트 전용 semantic token으로 단계적 치환장점:
주의점:
권장 구현 방향
1차 구현은 접근 A + C를 권장한다.
settingsStore또는themeStore에 테마 설정 추가Providers하위에ThemeInitializer/ThemeProvider추가html.darkclass를 적용해 기존.darkCSS 변수 사용bg-white/bg-bgGray고정값을 semantic token으로 변경우선 적용 화면 제안
QA 체크리스트
후속 검토 필요