Hardcoded Color 제거 및 Semantic Variable 도입을 통한 다크모드 시스템 설계

I Thought Dark Mode Was a 30-Minute Task. It Turned Into a Full Refactor

Marsha Teo2026년 5월 6일5분intermediate

AI 요약

Context

Tailwind CSS 유틸리티 클래스에 색상 값을 직접 하드코딩한 기존 구조로 인해 테마 변경 시 모든 요소의 개별 수정이 필요한 한계 발생. 단순 색상 반전 방식의 접근으로 인한 가독성 저하 및 렌더링 시점 차이로 인한 Flash 현상 노출.

Literal Value 기반의 설계를 Role 기반의 Semantic CSS Variables(--text-primary, --background 등) 구조로 전면 교체하여 테마 추상화 구현
Pure Black/White의 극단적 대비 대신 다층적인 Grey Scale을 적용하여 시각적 피로도 감소 및 가독성 확보
Tailwind Typography(prose) 플러그인의 기본 설정을 자체 Variable 시스템에 명시적으로 매핑하여 스타일 충돌 제거
정적 이미지 및 SVG 다이어그램의 경우 무리한 Dynamic Styling 대신 모드별 전용 Asset을 준비하여 렌더링 신뢰성 확보
Theme 결정 로직을 Rendering 단계 이전으로 전진 배치하여 JS 실행 전 테마 적용을 통한 Flash of Unstyled Content 제거

실천 포인트

1. 색상 정의 시 'dark-blue' 같은 색상명 대신 'bg-primary' 같은 역할 중심 명명법 적용 여부 확인

2. 고대비(Pure Black/White) 지양 및 적정 Contrast Ratio 준수 여부 검토

3. Third-party 라이브러리(Typography 등)의 기본 스타일과 자체 테마 변수의 매핑 전략 수립

4. Critical Rendering Path 상에서 테마 결정 로직의 위치가 최상단에 배치되었는지 확인

태그