[🌙다크 모드 - 1부] 다크 모드 도입 실패 회고록

alt text

다크 모드 도입 실패기 : 예상치 못한 거대한 벽

도입: 익숙함이 안겨준 방심

블로그의 디자인적 기능 개선을 진행하고 싶어, '다크 모드'를 도입하기로 마음먹었다. 많은 어려움을 겪었던 다양한 기능 추가 (특히 이미지 리사이징..) 를 진행해보니, 프론트엔드에서 다크모드 도입은 그리 어려운 작업은 아닐 거라 생각했다. 특히 이전에 진행했던 단순 HTML, CSS, JavaScript로 만들었던 내 포트폴리오 웹사이트 RollerCoaster 에서는 localStorage와 CSS 변수를 이용해 예상외로 쉽게 적용한 경험이 있었기 때문이다.

그때의 경험은 간단했다. CSS 변수로 색상 시스템을 정의하고, JavaScript로 <body> 태그에 data-theme="dark" 속성 하나만 토글해주면 모든 것이 마법처럼 바뀌었다. 그 익숙함과 자신감은, 내가 마주할 거대한 벽의 높이를 가늠하지 못하게 만든 가장 큰 원인이었다.

내 새로운 블로그 프로젝트의 기술 스택은 이전과는 차원이 달랐다.

Next.js 15 (App Router)
React 19
Tailwind CSS v4
Toast UI Editor

현대적인 웹 개발의 편리함을 모두 누리고 있었지만, 바로 그 '편리함'을 제공하는 각 시스템의 복잡한 상호작용이 이번 다크 모드 도입에 발목을 잡히게 될 줄은 꿈에도 몰랐다.

Phase 1: 기본 설정, 순조로운 출발

처음 진행은 순조로웠다. next-themes 라이브러리를 설치하고, ThemeProvider를 앱 전체에 적용했다. tailwind.config.js에 darkMode: 'class'를 추가하고, globals.css에 라이트/다크 모드용 CSS 변수를 정의했다.

/* globals.css */
:root {
  --bg-primary: #ffffff;
  --text-primary: #111827;
  /* ... */
}

html.dark {
  --bg-primary: #111827;
  --text-primary: #f9fafb;
  /* ... */
}

Header, PostCard 등 내가 직접 만든 컴포넌트들은 dark: 접두사를 붙여주자마자 마법처럼 다크 모드에 반응하기 시작했다. 여기까지는 모든 것이 예상대로였다. 문제는 가장 중요한 콘텐츠 영역, 바로 Toast UI Editor에서 시작되었다.

Phase 2: 첫 번째 충돌, Viewer의 정전과 Editor의 침묵

처음 다크모드를 도입하고 메인 페이지는 잘 적용되었다.

alt text

하지만 상세페이지로 들어가자 대참사가 일어났다. 암전된 게시글이 보이기 시작했다.

alt text

테마 토글 버튼을 눌러 <html> 태그에 class="dark"가 붙어도, 에디터는 요지부동이었다. 페이지의 모든 것이 어두워졌지만, 에디터만은 새하얀 배경을 고집하며 홀로 빛나고 있었다.

alt text

이때부터 기나긴 디버깅 여정이 시작되었다.

가설 1: SSR 문제일 것이다. Toast UI Editor는 브라우저 환경에 의존적이니, next/dynamic으로 SSR을 비활성화하면 해결될 거라 생각했다.

// Editor.tsx
const TuiEditor = dynamic(
  () => import('@toast-ui/react-editor').then((mod) => mod.Editor),
  { ssr: false }
);

결과는? 실패. SSR 에러는 사라졌지만, 에디터는 여전히 하얗다.

가설 2: 라이브러리의 공식 API를 사용하지 않았다. 리서치를 통해 theme prop과 key를 이용한 강제 재마운트 전략을 알게 되었다. "이거면 되겠지."

// Editor.tsx
<TuiEditor
  key={theme}
  theme={theme === 'dark' ? 'dark' : 'default'}
  // ...
/>

결과는? 또다시 실패. 에디터는 꼼짝도 하지 않았다.

Phase 3: 보이지 않는 적, CSS와의 전쟁

이제 문제는 코드 로직이 아닌, 보이지 않는 CSS의 세계에 있다는 것을 직감했다.

가설 3: 다크 모드 CSS 파일이 로드되지 않았다. layout.tsx에서 toastui-editor-dark.css를 직접 import하고, 브라우저 Network 탭을 확인했다. 파일은 로드되고 있었다. 하지만 Next.js의 CSS 번들링 방식이 의심스러워, globals.css에서 @import하는 방식으로 변경도 해보았다. 결과는 같았다. CSS 파일은 분명히 존재했다.

가설 4: CSS 우선순위(Specificity) 문제다. "Tailwind CSS의 막강한 기본 스타일이 Toast UI의 스타일을 덮어쓰고 있는 게 분명해." 나는 tailwind.config.js에 important: '#app-root'를 설정하여 Tailwind의 영향 범위를 제한하고, globals.css 최하단에 !important를 동원한 오버라이드 규칙까지 추가했다.

/* globals.css */
html.dark #app-root .toastui-editor-defaultUI {
  background-color: var(--bg-secondary) !important;
  /* ... */
}

결과는? 처참한 실패. 내 모든 노력에도 불구하고 에디터의 배경색은 변하지 않았다. 개발자 도구의 Styles 탭은 내가 추가한 !important 규칙이 적용조차 되지 않았거나, 다른 무언가에 의해 무시되고 있음을 보여주고 있었다.

alt text

중간 결론: 미궁 속으로

모든 표준적인 해결책을 시도했지만, 문제는 해결되지 않았다. CSS 파일은 로드되었고, <html> 태그의 클래스는 변경되었으며, 에디터 컴포넌트는 재마운트까지 되고 있었다. 하지만 그 모든 신호를 에디터는 철저히 무시하고 있었다.

마치 모든 부품이 정상인데 시동이 걸리지 않는 자동차를 마주한 기분이었다. 문제는 내가 아는 영역 너머, Next.js의 빌드 시스템과 Tailwind v4, 그리고 Toast UI Editor라는 세 개의 거대한 블랙박스가 상호작용하는 깊은 곳에 숨어있는 것 같았다.

나는 이 문제를 해결하기 위해, 더 깊은 심연으로 들어가기로 결심했다.

Phase 4: 마지막 지푸라기, 진단과 검증

1부에서 모든 표준적인 해결책이 실패로 돌아간 후, 나는 접근 방식을 바꾸기로 했다. 더 이상 새로운 해결책을 '시도'하는 대신, 문제의 근본 원인을 '진단'하는 데 집중하기로 한 것이다. "왜 안 되지?"라는 막연한 질문 대신, "지금 무슨 일이 일어나고 있는가?"라는 구체적인 질문을 던지기 시작했다.

이를 위해 브라우저 개발자 도구의 콘솔에 몇 가지 진단 스크립트를 실행하여, 눈에 보이지 않는 내부 동작을 '팩트'로 수집했다.

진단 1: CSS 규칙은 정말 존재하는가? document.styleSheets를 모두 뒤져 .toastui-editor-dark 관련 규칙이 있는지 확인했다.

// 콘솔 실행 결과
{ ..., hasDark: true }

결론: 존재했다. CSS 파일은 정상적으로 로드되었고, 다크 모드 규칙도 번들 안에 포함되어 있었다.

진단 2: 에디터의 내부 구조는 예상과 같은가? <iframe>이나 shadow DOM을 사용한다면 외부 CSS가 적용되지 않을 수 있다. 에디터의 DOM 구조를 확인했다.

// 콘솔 실행 결과
Iframe Found: false
ShadowRoot Present: false

결론: 아니었다. 에디터는 평범한 div로 렌더링되고 있었다. 외부 스타일이 적용되지 않을 이유가 없었다.

진단 3: 다크 모드 클래스는 제대로 주입되고 있는가? useLayoutEffect를 사용해 .toastui-editor-dark 클래스를 주입하는 로직이 정말 동작하는지 확인했다.

// 콘솔 실행 결과 (Elements 탭 확인)
<div class="toastui-editor-defaultUI toastui-editor-dark">...</div>

결론: 성공적으로 주입되고 있었다. <html> 태그의 클래스가 dark로 바뀌면, 에디터의 루트 div에도 .toastui-editor-dark 클래스가 분명히 추가되었다.

심연의 끝: 모든 것이 정상인데, 아무것도 변하지 않는다

모든 진단 결과는 나를 더 깊은 미궁으로 빠뜨렸다.

다크 모드 CSS 규칙은 존재한다.
스타일을 적용할 DOM 요소도 존재한다.
두 요소를 연결할 클래스도 정상적으로 주입된다.

하지만 결과는 변하지 않았다. 에디터는 여전히 새하얀 모습 그대로였다. 이 현상은 CSS의 기본 동작 원리를 거스르는 것처럼 보였다. 이는 단순히 디버깅으로 해결될 수준을 넘어선, 빌드 시스템(Next.js, Turbopack, PostCSS)과 라이브러리(Tailwind CSS v4, Toast UI Editor) 간의 복잡한 상호작용 혹은 도입 방식에 대한 리서치의 부정확성 문제임을 직감했다.

결론: 전략적 후퇴, 그리고 다음을 위한 약속

모든 문제에는 해결책이 있다고 믿지만, 그 해결책을 찾는 데 드는 '비용'을 항상 고려해야 한다. 현재 이 문제를 해결하기 위해서는 Next.js나 Tailwind의 빌드 프로세스 내부를 파고들거나, Toast UI Editor의 CSS 전체를 !important를 사용하여 재작성해야 할 수도 있다. 계속해서 근본적인 원인을 찾지 못하고 디버깅 상황을 해결하지 못하는 것은 의미가 없다고 판단했다.

그래서 나는 다크모드 도입에 대해 '잠정 중단' 이라는, 어쩌면 가장 어려운 결정을 내리기로 했다. 이것은 포기가 아닌, 더 중요한 목표에 집중하기 위한 전략적 후퇴다.

다만, Toast UI Editor와 다양한 React환경에서 다크모드를 도입한 다른 훌륭하신 분들의 포스팅을 보며 학습하고, 검증하고 다시 도전해볼 예정이다.

다음 포스팅에서는 반드시 이 벽을 넘어, Deep Dive! 블로그에 완벽한 다크 모드를 적용할 것이다.

반드시..👊

[🌙다크 모드 - 1부] 다크 모드 도입 실패 회고록

다크 모드 도입 실패기 : 예상치 못한 거대한 벽

도입: 익숙함이 안겨준 방심

Phase 1: 기본 설정, 순조로운 출발

Phase 2: 첫 번째 충돌, Viewer의 정전과 Editor의 침묵

Phase 3: 보이지 않는 적, CSS와의 전쟁

중간 결론: 미궁 속으로

Phase 4: 마지막 지푸라기, 진단과 검증

심연의 끝: 모든 것이 정상인데, 아무것도 변하지 않는다

결론: 전략적 후퇴, 그리고 다음을 위한 약속

Administrator