🌙 Tailwind 7장: 다크 모드 구현

2026년 3월 5일 수정됨

📋 개요

Tailwind dark variant 로 다크 모드 완벽 구현 — class 전략부터 시스템 설정 연동까지

📋 목차

📌 이 문서를 읽기 전에
🤔 왜 알아야 하는가
🏗️ 비유로 먼저 이해하기
🌙 Tailwind 다크 모드 두 가지 전략
🎨 다크 모드 색상 설계 원칙
💻 실전: 영수네 커뮤니티 다크 모드 적용
⚙️ Next.js 에서 다크 모드 토글 구현
🚨 흔한 실수와 주의사항
🏁 이번에 배운 내용 총정리
📝 마무리 퀴즈
[🐣 영철이의 퇴근 일기](#-영철이의-퇴근 일기)
🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 18분

🎯 이 문서를 다 읽으면 할 수 있는 것

dark: variant 를 자유롭게 써서 다크 모드 스타일을 정의할 수 있다
class 전략으로 JS 기반 다크 모드 토글을 구현할 수 있다
다크 모드에서 색상 계층을 올바르게 설계할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

🎨 영숙 (디자이너): "영철 님, 저 피그마에 다크 모드도 다 그려놨어요. 이제 구현 부탁드려도 될까요?"
🐣 영철: "...다크 모드요? 그게 얼마나 걸릴지..."
🦁 영호 (리드): "영철 님, Tailwind 쓰고 있으면 생각보다 빨리 돼요. bg-white dark:bg-gray-900 이런 식으로 dark: 접두사만 붙이면 되거든요."
🐣 영철: "아, 반응형처럼 접두사 방식이군요?"
🦁 영호: "정확해요. 이미 반응형 했으면 다크 모드는 금방이에요."

🤔 왜 알아야 하는가

다크 모드는 이제 선택이 아닌 필수야. iOS, Android, macOS, Windows 모두 시스템 다크 모드를 지원하고, 사용자들은 자신이 선호하는 모드를 기대해.

단순히 "배경을 어둡게 하는 것" 이 아니야. 눈의 피로도 감소, 배터리 절약 (OLED 화면), 야간 사용 편의성 등 실질적인 UX 이점이 있어.

영수네 커뮤니티에 다크 모드가 없으면? 야간에 스터디 검색하다가 눈이 터지는 사용자들이 이탈해.

🏗️ 비유로 먼저 이해하기

다크 모드 = 룸 라이트 스위치

방에 일반 조명과 무드 등 두 가지가 있다고 생각해. dark: 클래스는 "무드 등 켜졌을 때 이 색상으로 바꿔" 라는 지시야.

라이트 모드 (일반 조명): bg-white text-gray-900
다크 모드 (무드 등): dark:bg-gray-900 dark:text-white

💡 한 줄로 기억하기
dark: 는 hover:, md: 와 같은 variant. "다크 모드일 때 이 스타일을 적용해."

🌙 Tailwind 다크 모드 두 가지 전략

전략 1: `media` 방식 (시스템 설정 자동 감지)

/* tailwind.config 없이 기본값: prefers-color-scheme 자동 감지 */
/* Tailwind v4 에서는 @import "tailwindcss" 만 하면 미디어 기반이 기본 */

<!-- 시스템이 다크 모드일 때 자동으로 dark: 적용 -->
<div class="bg-white dark:bg-gray-900">
  <p class="text-gray-900 dark:text-white">텍스트</p>
</div>

장점: 별도 JS 로직 없이 시스템 설정에 자동 연동
단점: 사용자가 앱 안에서 직접 토글 불가

전략 2: `class` 방식 (수동 제어 — 권장)

/* CSS 파일에 설정 */
@import "tailwindcss";
@variant dark (&:where(.dark, .dark *));

또는 tailwind.config.js:

// tailwind.config.js
module.exports = {
  darkMode: 'class',  // 'media' 대신 'class' 사용
  // ...
}

<!-- html 또는 body 에 .dark 클래스가 붙으면 dark: 적용 -->
<html class="dark">
  <body>
    <div class="bg-white dark:bg-gray-900">다크 모드 적용됨</div>
  </body>
</html>

장점: 사용자가 앱 내에서 토글 가능, localStorage 저장으로 설정 유지
단점: JS 로 .dark 클래스 토글 로직 필요

📌 실무에서는 class 방식이 표준이야. 사용자에게 선택권을 주는 게 더 좋은 UX 거든.

🎨 다크 모드 색상 설계 원칙

다크 모드는 단순히 색상을 반전시키는 게 아니야. 대비(Contrast)와 계층(Hierarchy) 을 유지해야 해.

라이트 모드 vs 다크 모드 색상 대응표

라이트 모드                    다크 모드
──────────────────────────────────────────────
bg-white                   → dark:bg-gray-900   (페이지 배경)
bg-gray-50                 → dark:bg-gray-800   (섹션 배경)
bg-gray-100                → dark:bg-gray-700   (카드 배경)
border-gray-200            → dark:border-gray-700 (테두리)
text-gray-900              → dark:text-white     (주요 텍스트)
text-gray-600              → dark:text-gray-300  (보조 텍스트)
text-gray-400              → dark:text-gray-500  (힌트 텍스트)
bg-blue-600                → dark:bg-blue-500    (CTA 버튼 — 밝게)
text-blue-600              → dark:text-blue-400  (링크 색상 — 밝게)

잘못된 다크 모드 vs 올바른 다크 모드

{/* ❌ 잘못된 방식: 단순 반전 — 계층 구조가 사라짐 */}
<div className="bg-white dark:bg-black text-black dark:text-white">
  {/* 배경이 완전 검정 → 카드가 배경에서 분리 안 됨 */}
  <div className="bg-gray-100 dark:bg-gray-900">카드</div>
</div>
 
{/* ✅ 올바른 방식: 계층 유지 */}
<div className="bg-gray-50 dark:bg-gray-900">       {/* 페이지 배경 */}
  <div className="bg-white dark:bg-gray-800">      {/* 카드 배경 (배경보다 밝게) */}
    <div className="bg-gray-50 dark:bg-gray-700">  {/* 내부 섹션 (카드보다 밝게) */}
      카드 내용
    </div>
  </div>
</div>

💻 실전: 영수네 커뮤니티 다크 모드 적용

기본 레이아웃

// 페이지 루트: 라이트/다크 모드 배경 설정
function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      {/* body 에 다크 모드 배경색 적용 */}
      <body className="bg-gray-50 text-gray-900 dark:bg-gray-900 dark:text-white">
        <Navbar />
        <main>{children}</main>
        <Footer />
      </body>
    </html>
  );
}

스터디 카드 다크 모드

function StudyCard({ title, description, tag, memberCount }: Props) {
  return (
    <div className="
      group rounded-xl border p-5 shadow-md transition-all
      hover:-translate-y-1 hover:shadow-lg
 
      {/* 라이트 모드 */}
      bg-white border-gray-200
 
      {/* 다크 모드 */}
      dark:bg-gray-800 dark:border-gray-700
    ">
      {/* 태그 배지 */}
      <span className="
        mb-3 inline-block rounded-full px-3 py-0.5 text-xs font-semibold
        bg-blue-100 text-blue-700
        dark:bg-blue-900/50 dark:text-blue-300
      ">
        {tag}
      </span>
 
      {/* 제목 */}
      <h3 className="
        mb-2 text-lg font-bold transition-colors
        text-gray-900 group-hover:text-blue-600
        dark:text-white dark:group-hover:text-blue-400
      ">
        {title}
      </h3>
 
      {/* 설명 */}
      <p className="mb-4 line-clamp-2 text-sm text-gray-500 dark:text-gray-400">
        {description}
      </p>
 
      {/* 하단 */}
      <div className="
        flex items-center justify-between border-t pt-4
        border-gray-100 dark:border-gray-700
      ">
        <span className="text-xs text-gray-400 dark:text-gray-500">
          👥 {memberCount}명
        </span>
        <button className="
          rounded-lg px-3 py-1.5 text-xs font-medium transition-colors
          bg-blue-600 text-white hover:bg-blue-700
          dark:bg-blue-500 dark:hover:bg-blue-400
        ">
          참여하기
        </button>
      </div>
    </div>
  );
}

내비게이션 바 다크 모드

function Navbar() {
  return (
    <nav className="
      sticky top-0 z-10 border-b
      bg-white/80 backdrop-blur-sm border-gray-200
      dark:bg-gray-900/80 dark:border-gray-700
    ">
      <div className="mx-auto flex h-16 max-w-6xl items-center justify-between px-4">
        {/* 로고 */}
        <a href="/" className="font-bold text-blue-600 dark:text-blue-400">
          📚 영수네 커뮤니티
        </a>
 
        {/* 메뉴 */}
        <div className="flex items-center gap-4">
          <a className="
            text-sm transition-colors
            text-gray-600 hover:text-blue-600
            dark:text-gray-300 dark:hover:text-blue-400
          ">
            스터디 찾기
          </a>
          <DarkModeToggle />
        </div>
      </div>
    </nav>
  );
}

⚙️ Next.js 에서 다크 모드 토글 구현

next-themes 라이브러리를 사용하는 것이 Next.js 프로젝트의 표준이야.

설치

npm install next-themes

설정

// app/providers.tsx
'use client';
 
import { ThemeProvider } from 'next-themes';
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      attribute="class"        // html 요소에 class="dark" 로 적용
      defaultTheme="system"    // 기본값: 시스템 설정 따름
      enableSystem={true}      // 시스템 설정 감지 허용
    >
      {children}
    </ThemeProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" suppressHydrationWarning>  {/* suppressHydrationWarning 필수! */}
      <body className="bg-gray-50 dark:bg-gray-900">
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

다크 모드 토글 버튼

// components/DarkModeToggle.tsx
'use client';
 
import { useTheme } from 'next-themes';
import { useEffect, useState } from 'react';
 
export function DarkModeToggle() {
  const { theme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
 
  // Hydration 불일치 방지 — 반드시 필요!
  useEffect(() => setMounted(true), []);
  if (!mounted) return null;
 
  return (
    <button
      onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
      className="
        rounded-lg p-2 transition-colors
        text-gray-600 hover:bg-gray-100
        dark:text-gray-400 dark:hover:bg-gray-800
      "
      aria-label="다크 모드 토글"
    >
      {theme === 'dark' ? '☀️' : '🌙'}
    </button>
  );
}

⚠️ suppressHydrationWarning 과 mounted 체크 이유: Next.js 는 서버에서 HTML 을 생성할 때 다크 모드 상태를 모르기 때문에 서버/클라이언트 불일치가 발생해. suppressHydrationWarning 으로 경고를 억제하고, useEffect 로 마운트 후에만 렌더링해서 안전하게 처리해.

🚨 흔한 실수와 주의사항

실수 1: 이미지에 다크 모드 적용

{/* ❌ 다크 모드에서 이미지가 너무 밝게 보임 */}
<img src="/logo.png" alt="로고" />
 
{/* ✅ 다크 모드에서 이미지 밝기 약간 감소 */}
<img src="/logo.png" alt="로고" className="dark:opacity-80" />
 
{/* ✅ 또는 다크 모드용 별도 이미지 */}
<img
  src="/logo-light.png"
  alt="로고"
  className="dark:hidden"
/>
<img
  src="/logo-dark.png"
  alt="로고"
  className="hidden dark:block"
/>

실수 2: 하드코딩된 흰색 배경 문자

{/* ❌ 다크 모드에서 흰 배경에 흰 글자 → 안 보임 */}
<p className="text-white">흰 글자</p>
 
{/* ✅ 라이트에서 어두운 글자, 다크에서 밝은 글자 */}
<p className="text-gray-900 dark:text-white">올바른 글자</p>

실수 3: 색상 밝기 방향 혼동

{/* ❌ 다크 모드에서 더 어두운 색을 쓰는 실수 */}
<button className="bg-blue-600 dark:bg-blue-800">  {/* 다크에서 더 어두워서 안 보임 */}
 
{/* ✅ 다크 모드에서는 배경이 어둡기 때문에 버튼을 오히려 밝게 */}
<button className="bg-blue-600 dark:bg-blue-400">

🏁 이번에 배운 내용 총정리

개념	설명
`dark:` variant	다크 모드일 때 적용되는 스타일
media 전략	시스템 설정 자동 감지
class 전략	`html.dark` 클래스로 수동 제어 (권장)
색상 계층	라이트: 밝음→어둠, 다크: 어둠→밝음
next-themes	Next.js 다크 모드 표준 라이브러리
Hydration 주의	`suppressHydrationWarning` + `mounted` 체크

📝 마무리 퀴즈

Q1. 영철이가 카드 배경색을 "라이트 모드에서 흰색, 다크 모드에서 어두운 회색" 으로 만들고 싶다. 올바른 클래스는?

✅ 정답: bg-white dark:bg-gray-800

💡 상세 해설:

bg-white: 기본(라이트 모드) 흰색 배경.
dark:bg-gray-800: 다크 모드에서 어두운 회색(#1f2937) 배경.
왜 gray-900 이 아닌 gray-800 인가? 페이지 전체 배경이 dark:bg-gray-900 이면, 카드는 배경보다 약간 밝은 gray-800 을 써서 계층 구조를 유지해야 해.
📌 핵심 기억법: "다크 모드 색상 계층: 페이지 배경 900 → 카드 800 → 내부 700."

Q2. Next.js 에서 next-themes 를 사용할 때 suppressHydrationWarning 을 <html> 태그에 추가해야 하는 이유는?

✅ 정답: 서버에서 HTML 렌더링 시 다크 모드 상태를 알 수 없어 서버/클라이언트 불일치(Hydration Mismatch)가 발생하기 때문에, 이 경고를 억제하기 위해 필요하다.

💡 상세 해설:

Next.js 는 서버에서 HTML 을 미리 생성해. 이때 다크 모드 설정(localStorage 에 저장된)을 읽을 수 없어서 항상 기본 테마로 렌더링해.
클라이언트에서 마운트 후 localStorage 를 읽어 다크 모드를 적용하면, 서버 HTML 과 클라이언트 결과가 달라져 Hydration 오류 발생.
suppressHydrationWarning 은 이 특정 요소(<html>)에서의 Hydration 불일치를 React 가 무시하게 해. class 속성이 서버/클라이언트에서 달라도 경고 없음.
📌 핵심 기억법: "서버는 다크 모드 모른다 → suppressHydrationWarning 으로 평화롭게."

Q3. 다크 모드에서 CTA 버튼(bg-blue-600)의 색상 전략으로 올바른 것은?

✅ 정답: bg-blue-600 dark:bg-blue-500 처럼 다크 모드에서 더 밝은 값을 사용한다.

💡 상세 해설:

다크 모드에서 배경이 어두워지기 때문에, 버튼도 동일한 밝기를 유지하려면 오히려 더 밝은 색상을 써야 대비(Contrast)가 유지돼.
blue-600 (라이트) → blue-500 (다크): 숫자가 낮을수록 밝아.
반대로 생각하면 안 돼: 다크 모드에 blue-700, blue-800 을 쓰면 배경이 어두운데 버튼도 어두워서 구분이 안 돼.
📌 핵심 기억법: "다크 모드 = 배경이 어두움 = 앞에 오는 요소는 더 밝게."

🐣 영철이의 퇴근 일기

다크 모드가 이렇게 간단한 줄 몰랐다. dark: 접두사 하나로 끝나는데, 그동안 왜 이걸 어렵게 생각했는지 모르겠다.

next-themes 써서 토글 버튼 만든 것도 생각보다 금방 됐다. suppressHydrationWarning 때문에 좀 헤맸는데, 영호 님이 "서버에서는 다크 모드를 모르니까 클라이언트에서 마운트 된 후 처리해야 한다" 고 설명해주니까 바로 이해됐다.

💡 오늘의 교훈: "다크 모드는 색상 반전이 아니라 계층 유지다. 밝은 배경에서 어두운 텍스트 → 어두운 배경에서 밝은 텍스트, 그 계층을 그대로 뒤집어."

오늘 영숙 님이 피그마 다크 모드 시안 다 보내주셨는데, 이제 보니까 영숙 님도 같은 원칙으로 색상 계층을 설계하셨더라. 디자이너와 개발자의 언어가 같아지는 순간이 이런 거구나. 뿌듯하다! 오늘 저녁은 삼겹살 먹으러 가야겠다. 🥩

🌙 Tailwind 7장: 다크 모드 구현

📋 목차

📌 이 문서를 읽기 전에

🤔 왜 알아야 하는가

🏗️ 비유로 먼저 이해하기

🌙 Tailwind 다크 모드 두 가지 전략

전략 1: media 방식 (시스템 설정 자동 감지)

전략 2: class 방식 (수동 제어 — 권장)

🎨 다크 모드 색상 설계 원칙

라이트 모드 vs 다크 모드 색상 대응표

잘못된 다크 모드 vs 올바른 다크 모드

💻 실전: 영수네 커뮤니티 다크 모드 적용

기본 레이아웃

스터디 카드 다크 모드

내비게이션 바 다크 모드

⚙️ Next.js 에서 다크 모드 토글 구현

설치

설정

다크 모드 토글 버튼

🚨 흔한 실수와 주의사항

실수 1: 이미지에 다크 모드 적용

실수 2: 하드코딩된 흰색 배경 문자

실수 3: 색상 밝기 방향 혼동

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

🐣 영철이의 퇴근 일기

🔗 더 알아보기

전략 1: `media` 방식 (시스템 설정 자동 감지)

전략 2: `class` 방식 (수동 제어 — 권장)