UX/UI / Frontend • 2026. 02. 07

CSS 변수와 LocalStorage를 이용한 다크모드 완벽 구현 가이드

현대 웹 디자인에서 다크모드(Dark Mode)는 단순한 트렌드를 넘어 사용자의 눈 피로도를 줄이고 모바일 기기의 배터리를 절약하는 필수 기능이 되었습니다. eleslog.work 프로젝트를 진행하며 고민했던 '가장 깔끔하고 부드러운 테마 전환 기법'을 상세히 정리해 드립니다.

1. 시스템 테마 감지: prefers-color-scheme

사용자가 웹사이트에 접속했을 때 가장 먼저 확인해야 할 것은 사용자의 운영체제(OS) 설정입니다. CSS의 미디어 쿼리를 사용하면 자바스크립트 없이도 기본 시스템 테마를 반영할 수 있습니다.


/* 기본은 라이트 테마 */
:root {
  --bg-color: #ffffff;
  --text-color: #1e293b;
}

/* 시스템이 다크모드일 경우 자동 적용 */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-color: #0f172a;
    --text-color: #f8fafc;
  }
}

하지만 이 방식만으로는 사용자가 사이트 내에서 수동으로 테마를 변경하고 유지하는 기능을 제공할 수 없습니다. 이를 위해 CSS 변수(Custom Properties)와 자바스크립트의 결합이 필요합니다.

2. 전략적 설계: CSS 변수 계층 구조

모든 색상 값을 하드코딩하지 않고 변수로 관리하는 것이 첫 번째 단계입니다. data-theme 속성을 활용하여 테마를 전환하는 구조를 설계합니다.


/* theme.css */
:root[data-theme="light"] {
  --bg-main: #f8fafc;
  --text-main: #0f172a;
  --accent: #6366f1;
}

:root[data-theme="dark"] {
  --bg-main: #0f172a;
  --text-main: #f8fafc;
  --accent: #8b5cf6;
}

body {
  background-color: var(--bg-main);
  color: var(--text-main);
  transition: background-color 0.3s ease, color 0.3s ease;
}

3. LocalStorage를 활용한 테마 유지

사용자가 한 번 다크모드를 선택했다면, 다음 방문 시에도 해당 테마가 유지되어야 합니다. 브라우저의 LocalStorage는 테마 설정을 저장하기에 최적인 장소입니다.

핵심 로직:
사용자가 토글 버튼을 클릭하면 현재 테마를 반전시키고, 그 결과를 localStorage.setItem('theme', 'dark')와 같이 저장합니다. 페이지 로드 시에는 이 값을 읽어와 <html> 태그의 data-theme 속성에 주입합니다.

4. 고질적인 문제: '깜빡임(FOUC)' 현상 해결

많은 다크모드 구현체들이 범하는 실수 중 하나는 자바스크립트 파일을 <body> 끝부분에 배치하여, 페이지 로드 직후 0.1초 동안 하얀 화면이 보였다가 다크모드로 바뀌는 현상입니다.

이를 해결하기 위해서는 **'Blocking Script'**를 활용해야 합니다. HTML이 렌더링되기 전, <head> 섹션 내에서 즉시 실행 함수(IIFE)를 통해 테마를 적용하는 코드를 삽입합니다.


<head>
  <script>
    (function() {
      const savedTheme = localStorage.getItem('theme');
      const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      const theme = savedTheme || (systemDark ? 'dark' : 'light');
      document.documentElement.setAttribute('data-theme', theme);
    })();
  </script>
</head>

이 작은 스크립트 하나가 사용자 경험의 질을 결정짓습니다. DOM 콘텐츠가 그려지기 전에 속성을 주입하므로 사용자는 어떠한 시각적 불쾌함도 느끼지 않습니다.

5. CSS-Only 팁: :has() 선택자와 color-scheme

최신 브라우저에서는 자바스크립트 의존도를 더 낮출 수 있습니다. color-scheme 속성을 사용하면 브라우저의 기본 UI 요소(스크롤바, 버튼, 입력창)까지 시스템 테마에 맞춰 자동으로 스타일링됩니다.


:root {
  color-scheme: light dark; /* 브라우저에게 두 테마를 모두 지원함을 알림 */
}

마치며: 심미성을 더하는 디테일

다크모드는 단순히 배경을 검은색(#000000)으로 바꾸는 것이 아닙니다. 완전한 블랙보다는 깊은 감청색이나 짙은 회색을 사용하여 대비를 조절하고, 텍스트 역시 순수 흰색보다는 약간의 미색을 사용하여 가독성을 높여야 합니다.

eleslog.work에서 제공하는 부드러운 테마 전환과 눈이 편안한 색감 구성을 통해 여러분의 프로젝트에도 생명력을 불어넣어 보세요. 다음 포스팅에서는 다크모드에 최적화된 이미지 에셋 처리(SVG 필터 활용법)에 대해 알아보겠습니다.

목록으로 돌아가기