Inline Script와 CSS Variable을 통한 Theme Flash 제로 구현

A Practical CSS Variable Setup for Light/Dark Mode Without Theme Flash

Hasan Sarwer2026년 6월 30일9분beginner

AI 요약

Context

localStorage 기반 테마 설정 시 JavaScript 실행 시점과 HTML/CSS 파싱 시점의 차이로 인한 Theme Flash 현상 발생. 브라우저의 First Paint 이전까지 테마 결정 로직이 완료되지 않아 잘못된 테마가 일시적으로 렌더링되는 한계 존재.

Technical Solution

Semantic Variable 설계를 통한 컴포넌트 스타일과 테마 값의 완전한 분리
HTML root 요소에 data-theme 속성을 부여하여 CSS 선택자 기반의 테마 스위칭 구조 설계
prefers-color-scheme와 :not([data-theme="light"]) 선택자를 조합한 OS 설정 우선 적용 로직 구현
CSS 로드 전 내부에 즉시 실행 함수(IIFE) 형태의 Inline Script를 배치하여 First Paint 전 테마 결정
DOMContentLoaded 이벤트나 defer 속성 배제를 통한 렌더링 블로킹 시점의 의도적 활용으로 Flash 현상 원천 차단

실천 포인트

- 테마 결정 스크립트를 CSS 파일 링크보다 상단에 배치했는지 확인 - localStorage 접근 시 try-catch 문을 통한 예외 처리 적용 - OS 설정과 사용자 설정의 우선순위(User Preference > System Preference) 설계 반영 - CSS 변수 명명 시 색상값이 아닌 의미 중심의 Semantic Name 사용

태그

#Critical Rendering Path #Theme Flash #LocalStorage #CSS Variable #prefers-color-scheme

원문 읽기