Tailwind CSS 다크모드 구현 완벽 가이드 (2026년)

module.exports = {
  darkMode: 'class', // 'media' 또는 'class'
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class', // 'media' 또는 'class'
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

import { useState, useEffect } from 'react';

function DarkModeToggle() {
  const [darkMode, setDarkMode] = useState(false);

  useEffect(() => {
    // 로컬 스토리지에서 설정 불러오기
    const isDark = localStorage.getItem('darkMode') === 'true';
    setDarkMode(isDark);
    if (isDark) {
      document.documentElement.classList.add('dark');
    }
  }, []);

  const toggleDarkMode = () => {
    const newMode = !darkMode;
    setDarkMode(newMode);
    localStorage.setItem('darkMode', newMode);
    
    if (newMode) {
      document.documentElement.classList.add('dark');
    } else {
      document.documentElement.classList.remove('dark');
    }
  };

  return (
    <button onClick={toggleDarkMode}>
      {darkMode ? '?' : '☀️'}
    </button>
  );
}

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  <h1 className="text-2xl font-bold text-blue-600 dark:text-blue-400">
    제목입니다
  </h1>
  
  <p className="text-gray-600 dark:text-gray-300">
    본문 내용이에요
  </p>
  
  <button className="bg-blue-500 hover:bg-blue-600 dark:bg-blue-600 dark:hover:bg-blue-700">
    버튼
  </button>
</div>

색상 대비에 신경 써야 해요! 라이트모드에서 잘 보이던 텍스트가 다크모드에서는 안 보일 수도 있거든요. 특히 회색 계열 텍스트는 꼭 확인해보세요.

useEffect(() => {
  const stored = localStorage.getItem('darkMode');
  
  if (stored !== null) {
    // 사용자가 직접 선택한 적 있으면 그걸 사용
    const isDark = stored === 'true';
    setDarkMode(isDark);
    document.documentElement.classList.toggle('dark', isDark);
  } else {
    // 처음 방문이면 시스템 설정 확인
    const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    setDarkMode(systemPrefersDark);
    document.documentElement.classList.toggle('dark', systemPrefersDark);
  }
}, []);

# 설치
npm install next-themes

# _app.js 또는 layout.js
import { ThemeProvider } from 'next-themes'

export default function App({ Component, pageProps }) {
  return (
    <ThemeProvider attribute="class">
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

# 컴포넌트에서 사용
import { useTheme } from 'next-themes'

function ThemeToggle() {
  const { theme, setTheme } = useTheme()
  
  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      {theme === 'dark' ? '?' : '☀️'}
    </button>
  )
}

• tailwind.config.js에 darkMode 설정 추가했나요?
• 토글 버튼 만들었나요? (class 모드인 경우)
• localStorage에 사용자 선택 저장되나요?
• 모든 주요 컴포넌트에 dark: 스타일 적용했나요?
• 색상 대비 확인했나요?
• 페이지 새로고침 후에도 설정 유지되나요?

<button 
  id="theme-toggle"
  class="px-4 py-2 rounded-lg bg-gray-200 dark:bg-gray-700 
         text-gray-800 dark:text-gray-200 
         hover:bg-gray-300 dark:hover:bg-gray-600 
         transition-colors duration-200">
  ? 다크모드
</button>

<script>
const toggle = document.getElementById('theme-toggle');
const html = document.documentElement;

toggle.addEventListener('click', () => {
  if (html.classList.contains('dark')) {
    html.classList.remove('dark');
    localStorage.setItem('theme', 'light');
    toggle.textContent = '? 다크모드';
  } else {
    html.classList.add('dark');
    localStorage.setItem('theme', 'dark');
    toggle.textContent = '☀️ 라이트모드';
  }
});
</script>

<div class="flex items-center gap-3">
  <span class="text-gray-700 dark:text-gray-300">☀️</span>
  
  <label class="relative inline-block w-14 h-8 cursor-pointer">
    <input 
      type="checkbox" 
      id="theme-switch"
      class="sr-only peer"
    />
    <div class="w-full h-full bg-gray-300 rounded-full 
                peer-checked:bg-blue-600 
                transition-colors duration-300"></div>
    <div class="absolute left-1 top-1 w-6 h-6 bg-white rounded-full 
                peer-checked:translate-x-6 
                transition-transform duration-300 
                shadow-lg"></div>
  </label>
  
  <span class="text-gray-700 dark:text-gray-300">?</span>
</div>

<script>
const switchInput = document.getElementById('theme-switch');
const html = document.documentElement;

// 초기 상태 설정
switchInput.checked = html.classList.contains('dark');

switchInput.addEventListener('change', (e) => {
  if (e.target.checked) {
    html.classList.add('dark');
    localStorage.setItem('theme', 'dark');
  } else {
    html.classList.remove('dark');
    localStorage.setItem('theme', 'light');
  }
});
</script>

<div class="flex items-center gap-2 p-1 bg-gray-200 dark:bg-gray-700 rounded-lg">
  <button 
    data-theme="light"
    class="theme-btn px-3 py-2 rounded-md transition-colors">
    ☀️
  </button>
  <button 
    data-theme="system"
    class="theme-btn px-3 py-2 rounded-md transition-colors">
    ?
  </button>
  <button 
    data-theme="dark"
    class="theme-btn px-3 py-2 rounded-md transition-colors">
    ?
  </button>
</div>

<script>
const buttons = document.querySelectorAll('.theme-btn');
const html = document.documentElement;

function updateTheme(theme) {
  const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  
  // 버튼 활성화 상태 업데이트
  buttons.forEach(btn => {
    if (btn.dataset.theme === theme) {
      btn.classList.add('bg-white', 'dark:bg-gray-800', 'shadow-md');
    } else {
      btn.classList.remove('bg-white', 'dark:bg-gray-800', 'shadow-md');
    }
  });
  
  // 실제 테마 적용
  if (theme === 'system') {
    if (systemDark) {
      html.classList.add('dark');
    } else {
      html.classList.remove('dark');
    }
  } else if (theme === 'dark') {
    html.classList.add('dark');
  } else {
    html.classList.remove('dark');
  }
  
  localStorage.setItem('theme', theme);
}

buttons.forEach(btn => {
  btn.addEventListener('click', () => {
    updateTheme(btn.dataset.theme);
  });
});

// 초기 로드 시 설정
const savedTheme = localStorage.getItem('theme') || 'system';
updateTheme(savedTheme);

// 시스템 테마 변경 감지
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  const currentTheme = localStorage.getItem('theme');
  if (currentTheme === 'system') {
    updateTheme('system');
  }
});
</script>

1. 회전 효과: 스위치 내부 아이콘이 360도 회전하면서 전환돼요

2. 바운스 효과: 스위치가 살짝 튀는 듯한 느낌을 줘요

3. 페이드 효과: 전체 페이지가 부드럽게 색상 전환돼요

4. 스케일 효과: 버튼을 누를 때 살짝 작아졌다가 원래대로 돌아와요

<style>
@keyframes rotate-icon {
  0% { transform: rotate(0deg) scale(1); }
  50% { transform: rotate(180deg) scale(0.8); }
  100% { transform: rotate(360deg) scale(1); }
}

@keyframes bounce {
  0%, 100% { transform: translateX(0); }
  50% { transform: translateX(4px); }
}

.icon-rotate {
  animation: rotate-icon 0.5s ease-in-out;
}

.toggle-bounce {
  animation: bounce 0.3s ease-in-out;
}
</style>

<label class="relative inline-block w-16 h-8 cursor-pointer">
  <input type="checkbox" id="animated-switch" class="sr-only peer" />
  <div class="w-full h-full bg-gray-300 rounded-full 
              peer-checked:bg-gradient-to-r peer-checked:from-blue-500 peer-checked:to-purple-600
              transition-all duration-500"></div>
  <div class="absolute left-1 top-1 w-6 h-6 bg-white rounded-full 
              peer-checked:translate-x-8 
              transition-all duration-500 
              shadow-lg flex items-center justify-center">
    <span id="theme-icon" class="text-xs">☀️</span>
  </div>
</label>

<script>
const animatedSwitch = document.getElementById('animated-switch');
const icon = document.getElementById('theme-icon');
const html = document.documentElement;

animatedSwitch.addEventListener('change', (e) => {
  // 아이콘 회전 애니메이션
  icon.classList.add('icon-rotate');
  
  setTimeout(() => {
    if (e.target.checked) {
      icon.textContent = '?';
      html.classList.add('dark');
      localStorage.setItem('theme', 'dark');
    } else {
      icon.textContent = '☀️';
      html.classList.remove('dark');
      localStorage.setItem('theme', 'light');
    }
    icon.classList.remove('icon-rotate');
  }, 250);
});
</script>

토글 스위치를 구현할 때 가장 흔한 실수가 있어요. 바로 페이지 로드 시 깜빡임 현상이에요. localStorage를 확인하는 스크립트가 늦게 실행되면 라이트 모드가 잠깐 보였다가 다크 모드로 바뀌는 거죠. 이걸 방지하려면 HTML의 <head> 태그 안에 인라인 스크립트를 넣어서 최대한 빨리 실행되게 해야 해요!

• 대비율 7:1 이상 유지 - 접근성 WCAG AAA 기준이에요
• 순수한 검정(#000) 피하기 - 눈이 피로해지거든요
• 회색 계열은 5단계 이상 - 깊이감 표현에 필수예요
• 브랜드 컬러는 채도 조정 - 다크모드에서 너무 튀면 안 돼요

module.exports = {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        background: 'rgb(var(--color-background) / <alpha-value>)',
        foreground: 'rgb(var(--color-foreground) / <alpha-value>)',
        primary: 'rgb(var(--color-primary) / <alpha-value>)',
        card: 'rgb(var(--color-card) / <alpha-value>)',
      }
    }
  }
}

:root {
  --color-background: 255 255 255;
  --color-foreground: 17 24 39;
  --color-primary: 79 70 229;
  --color-card: 249 250 251;
}

.dark {
  --color-background: 15 23 42;
  --color-foreground: 241 245 249;
  --color-primary: 129 140 248;
  --color-card: 30 41 59;
}

페이지 로드 시 테마가 적용되기 전에 잠깐 흰 화면이 보이는 현상이에요. 이거 진짜 신경쓰이거든요. HTML head에 스크립트 넣어서 해결해야 해요.

<script>
  // body 렌더링 전에 실행
  (function() {
    const theme = localStorage.getItem('theme') || 
      (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
    
    document.documentElement.classList.toggle('dark', theme === 'dark');
  })();
</script>

<!-- 라이트 모드 로고 -->
<img 
  src="/logo-light.svg" 
  className="block dark:hidden h-8"
  alt="Logo"
/>

<!-- 다크 모드 로고 -->
<img 
  src="/logo-dark.svg" 
  className="hidden dark:block h-8"
  alt="Logo"
/>

• 색상 대비율 검증: Chrome DevTools의 Lighthouse로 체크하세요
• 포커스 표시: 키보드 사용자를 위해 포커스 링은 명확하게!
• 색상 의존 금지: 에러/성공을 색상만으로 표현하면 안 돼요
• prefers-reduced-motion: 애니메이션 끌 수 있게 해주세요

<button
  className="
    bg-blue-600 dark:bg-blue-500
    text-white
    px-6 py-3 rounded-lg
    focus:outline-none 
    focus:ring-4 focus:ring-blue-300 dark:focus:ring-blue-800
    hover:bg-blue-700 dark:hover:bg-blue-600
    transition-colors
    font-medium
  "
  aria-label="확인 버튼"
>
  확인
</button>

Safari 프라이빗 모드에서는 localStorage가 제한되니까, 에러 핸들링 꼭 해주세요. try-catch로 감싸는 거 잊지 마시고요. 그리고 모바일 Safari에서는 transition이 너무 많으면 버벅일 수 있어요. will-change 속성 쓰면 좀 나아져요.

<script>
  // HTML head 태그 안 최상단에 배치!
  (function() {
    const theme = localStorage.getItem('theme');
    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    
    if (theme === 'dark' || (!theme && systemDark)) {
      document.documentElement.classList.add('dark');
    }
  })();
</script>

토글 애니메이션을 추가하면 성능 문제를 사용자가 덜 느껴요. document.documentElement.style.transition = 'all 0.3s ease' 이렇게 설정하면 색상 변화가 부드럽게 보이거든요. 근데 애니메이션 끝나면 transition 속성 제거하는 거 잊지 마세요!

// theme-color 메타 태그 동적 변경
function updateThemeColor(isDark) {
  const metaThemeColor = document.querySelector('meta[name="theme-color"]');
  if (metaThemeColor) {
    metaThemeColor.setAttribute('content', isDark ? '#1f2937' : '#ffffff');
  }
}

// 다크모드 변경 시 호출
document.documentElement.classList.toggle('dark');
updateThemeColor(document.documentElement.classList.contains('dark'));

<!-- 다크모드에서 이미지 밝기 자동 조절 -->
<img 
  src="logo.png" 
  class="dark:brightness-90 dark:contrast-125"
  alt="로고"
/>

<!-- 아예 다른 이미지 사용하기 -->
<img 
  src="logo-light.png" 
  class="block dark:hidden"
  alt="로고"
/>
<img 
  src="logo-dark.png" 
  class="hidden dark:block"
  alt="로고"
/>

<!-- 배경 이미지도 조절 가능 -->
<div class="bg-hero-pattern dark:brightness-75 dark:saturate-150">
</div>

<input 
  type="text"
  placeholder="이름을 입력하세요"
  class="
    w-full px-4 py-3 rounded-lg
    bg-white dark:bg-gray-800
    border-2 border-gray-200 dark:border-gray-700
    text-gray-900 dark:text-gray-100
    placeholder:text-gray-400 dark:placeholder:text-gray-500
    focus:border-blue-500 dark:focus:border-blue-400
    focus:ring-4 focus:ring-blue-100 dark:focus:ring-blue-900
    transition-all duration-200
  "
/>

<!-- 체크박스도 커스텀 가능 -->
<input 
  type="checkbox"
  class="
    w-5 h-5 rounded
    text-blue-600 dark:text-blue-400
    bg-gray-100 dark:bg-gray-700
    border-gray-300 dark:border-gray-600
    focus:ring-blue-500 dark:focus:ring-blue-400
  "
/>

<!-- index.html의 head 최상단에 배치 -->
<script>
  // 페이지 로드 전에 실행
  (function() {
    const theme = localStorage.getItem('theme');
    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    
    if (theme === 'dark' || (!theme && systemDark)) {
      document.documentElement.classList.add('dark');
    }
  })();
</script>

<!-- currentColor 활용 -->
<svg 
  class="w-6 h-6 text-gray-600 dark:text-gray-400"
  fill="currentColor"
>
  <path d="..."/>
</svg>

<!-- 아이콘 전체 색상 반전 -->
<svg class="dark:invert">
  <path d="..."/>
</svg>

<!-- 필터로 색조 조절 -->
<svg class="dark:brightness-200 dark:contrast-75">
  <path d="..."/>
</svg>

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      // 고대비 모드용 색상
      colors: {
        'high-contrast': {
          bg: '#000000',
          text: '#ffffff',
          border: '#ffffff',
        }
      }
    }
  }
}

// CSS에서 사용
@media (prefers-contrast: high) {
  .dark {
    --bg-color: #000000;
    --text-color: #ffffff;
  }
}