CSS Variables 리맵핑을 통한 3,800개 하드코딩 클래스 일괄 전환

I added dark mode by editing CSS variables not 100 components

Sheryar Ahmed2026년 6월 30일4분intermediate

AI 요약

Context

130여 개 컴포넌트에 분산된 약 3,800개의 하드코딩된 색상 클래스로 인한 유지보수 비용 증가 상황. 개별 컴포넌트에 dark: 변이(variants)를 추가하는 방식은 작업 공수 과다 및 디자인 일관성 훼손이라는 구조적 한계 존재.

Codemod을 통한 하드코딩 색상을 Semantic Brand Scale(brand-*)로 일괄 전환하여 테마 추상화 계층 구축
Tailwind v4의 내부 작동 원리인 CSS Variables 참조 구조를 활용하여 .dark 셀렉터 내에서 Palette 변수값만 역전시키는 Token Remap 전략 채택
단순 색상 반전이 아닌 Depth Ordering 원칙을 적용하여 Canvas < Card < Surface 순의 시각적 계층 구조 유지
HTML Attribute Selector를 활용한 CSS 변수 재정의로 컴포넌트 수정 없는 사용자 정의 Accent Color 구현
Native Element의 렌더링 이슈 해결을 위해 전역 CSS 규칙을 통한 Option List 스타일 강제 지정

실천 포인트

1. 하드코딩된 색상을 의미론적 토큰(Semantic Token)으로 치환했는가

2. CSS Variables를 활용하여 런타임에 테마를 동적으로 교체할 수 있는 구조인가

3. Dark Mode 설계 시 단순 색상 반전이 아닌 표면 계층(Surface Hierarchy)의 깊이감을 고려했는가

4. 테마 변경 시 First Paint 전 Flash 현상을 방지하기 위한 inline script 전략이 포함되었는가

태그