[🌙다크 모드 - 2부] 다크 모드 도입 성공기

---

다크 모드 도입 성공기

---

실패의 기록, 모든 것의 시작점

1부의 마지막, 나는 '전략적 후퇴'라는 이름으로 다크 모드 도입을 잠정 중단했다. 모든 것이 정상적으로 동작하는 것처럼 보였지만, 결과적으로 아무것도 변하지 않았던 기이한 현상. 그 미스터리는 풀리지 않는 숙제처럼 머릿속을 맴돌았다.

포기는 아니었다. 다만, 무작정 부딪히는 대신 한 걸음 물러서서 내가 남긴 실패의 기록들을 처음부터 다시 읽어보기로 했다. 마치 사건 현장에 남겨진 증거들을 다시 살펴보는 수사관처럼. "왜 안 되지?"라는 막연한 탄식 대신, "내가 놓치고 있는 명백한 단서는 무엇인가?" 라는 질문으로 접근 방식을 바꾸었다.

그렇게 실패의 잿더미 속에서, 나는 이 기나긴 디버깅을 끝낼 첫 번째 실마리를 발견하기 시작했다.

새로운 단서, 새로운 전략

마음을 비우고 원점에서 다시 시작한 리서치는 이전과는 다른 것들을 보여주기 시작했다. 실패를 경험한 눈으로 보니, 무심코 지나쳤던 공식 문서의 문장과 개발 블로그의 코드 조각들이 새로운 의미로 다가왔다.

단서 1: Toast UI의 두 얼굴 Toast UI Editor의 공식 문서를 다시 읽던 중, theme prop에 대한 설명이 눈에 들어왔다. 초기 렌더링 시 테마를 지정하는 역할. 그 어디에도 동적으로 테마를 변경할 수 있다는 말은 없었다. 커뮤니티의 다른 개발자들은 이미 이 문제를 겪었고, 그들의 해결책은 한결같았다. "DOM에 직접 .toastui-editor-dark 클래스를 주입하라." theme prop은 허상이었고, 진짜는 DOM 조작에 있었다.

★단서 2★: Tailwind v4의 패러다임 전환 Tailwind v4의 문서는 tailwind.config.js의 darkMode: 'class'가 더 이상 표준이 아님을 명확히 하고 있었다. 대신, CSS 파일 안에서 직접 @custom-variant를 선언하는 새로운 방식을 제시했다. 스타일링의 제어권이 JavaScript 설정 파일에서 순수 CSS로 넘어온 것이다.

단서 3: Next.js와 클라이언트의 시간차 App Router 환경에서의 다크 모드 구현 예제들은 하나같이 suppressHydrationWarning 속성과 'Mounted' 상태 패턴을 언급하고 있었다. 서버는 사용자의 테마 설정을 알지 못한 채 페이지를 그리고, 클라이언트는 뒤늦게 localStorage를 확인하여 테마를 적용한다. 이 시간차로 인해 발생하는 서버와 클라이언트의 HTML 불일치, 즉 하이드레이션 오류는 반드시 해결해야 할 문제였다.

이 세 가지 단서는 안개 속에 있던 범인의 윤곽을 드러내고 있었다. 범인은 '알 수 없는 빌드 시스템'이라는 거대한 유령이 아니었다. 범인은 바로 '내가 정확히 알지 못했던 라이브러리와 프레임워크의 구체적인 동작 방식' 이었다.

견고한 토대 쌓기

새로운 단서들을 바탕으로, 나는 1부와는 정반대의 전략을 세웠다. 모든 것을 Next.js의 빌드 시스템에 맡기는 '통합'이 아닌, 각자의 역할을 명확히 정의하고 제어하는 '분리'와 '정교한 제어' 전략이었다.

먼저, next-themes를 다시 설치하고 ThemeProvider를 설정했다. 이번에는 defaultTheme="light", enableSystem={false} 옵션을 명시하여, 오직 나의 코드만이 테마를 제어할 수 있도록 통제권을 가져왔다.

다음으로, 하이드레이션 오류를 원천적으로 봉쇄하기 위해 'Mounted' 상태 패턴을 도입했다. useEffect를 사용해 컴포넌트가 클라이언트에서 완전히 렌더링된 후에만 테마 관련 스타일을 적용하는 방식이다.

// Mounted 상태 패턴 예시
const [mounted, setMounted] = useState(false);
const { theme } = useTheme();

useEffect(() => {
  setMounted(true);
}, []);

// 렌더링 부분
// theme === 'dark' && mounted ? 'dark-class' : ''

이 견고한 기반 위에, framer-motion을 이용한 부드러운 애니메이션 토글 버튼을 구현했다. 이 작은 성공은 앞으로 나아갈 길에 대한 확신을 주었다.

Editor와의 재회, 첫 번째 성공

과거의 실패를 반복하지 않기 위해, Editor.tsx 컴포넌트를 수정하며 새로운 전략을 적용했다.

1. wrapperRef 패턴 도입: Editor 컴포넌트를 div로 감싸고 ref를 연결했다. Editor의 내부 API에 의존하는 대신, 이 wrapper 내부에서 DOM을 탐색하는 방식은 훨씬 안정적이다.
2. useLayoutEffect를 이용한 클래스 주입: theme 상태가 바뀔 때마다, wrapper 내부에서 .toastui-editor-defaultUI 요소를 찾아 .toastui-editor-dark 클래스를 직접 추가하거나 제거했다.

// Editor.tsx의 핵심 로직
useLayoutEffect(() => {
  const wrapper = wrapperRef.current;
  if (!wrapper) return;

  const tuiEl = wrapper.querySelector<HTMLElement>('.toastui-editor-defaultUI');
  if (tuiEl) {
    if (theme === 'dark' && mounted) {
      tuiEl.classList.add('toastui-editor-dark');
    } else {
      tuiEl.classList.remove('toastui-editor-dark');
    }
  }
}, [theme, mounted]);

결과는 놀라웠다. 테마 토글 버튼을 누르자, 에디터는 거짓말처럼 다크 모드로 완벽하게 전환되었다. 툴바, 배경, 텍스트 색상까지 모든 것이 일사불란하게 움직였다. 길고 길었던 싸움의 첫 번째 승리였다.

이제 마지막 관문, Viewer만이 남아있었다. 하지만 나는 아직 마지막 시련이 나를 기다리고 있다는 사실을 알지 못했다.

최후의 난관: Tailwind prose와의 CSS 전쟁

Editor 적용에 성공하며 승리를 예감했지만, 마지막 관문인 Viewer에서 1부의 악몽이 재현되었다. 다크 모드로 전환해도 본문 텍스트가 까맣게 남아 가독성이 전혀 확보되지 않았다. 코드 블록 주변에는 원치 않는 이중 테두리가 생겨 디자인을 해치고 있었다.

문제는 더 이상 미궁 속에 있지 않았다. 나는 브라우저 개발자 도구라는 가장 강력한 무기를 들고 '과학 수사'에 착수했다. Styles 탭과 Computed 탭을 오가며 모든 CSS 규칙을 끈질기게 추적한 끝에, 마침내 진짜 범인의 정체를 밝혀냈다.

범인은 Toast UI도, Next.js도 아니었다. 바로 내가 편리하게 사용하던 Tailwind Typography 플러그인, @tailwindcss/typography의 prose 클래스였다.

prose는 마크다운 콘텐츠를 아름답게 꾸며주기 위해 매우 구체적이고 강력한 스타일 규칙들을 생성한다. 이 규칙들이 Toast UI의 다크 모드 스타일보다 우선순위가 높아, 내 모든 노력을 덮어쓰고 있었던 것이다. 이 CSS 우선순위(Specificity) 전쟁에서 이기지 못하면, 다크 모드는 영원히 미완성으로 남을 터였다.

역전의 코드: 단 한 줄의 CSS로 전쟁을 끝내다

prose와의 전쟁에서 이기기 위한 전략은 명확했다. prose의 규칙보다 더 구체적인, 우리만의 규칙을 만들어 전세를 뒤집는 것이었다.

먼저, 코드 블록의 이중 테두리 문제를 해결하기 위해 globals.css에 다음과 같은 코드를 추가했다.

/* globals.css */
.prose pre {
  border: none !important;
  background-color: transparent !important;
}

!important 키워드는 prose가 설정한 모든 border와 background를 강제로 무력화시켰다. 이로써 react-syntax-highlighter의 materialDark 테마와 내가 직접 만든 커스텀 테두리만 화면에 남게 되었다.

다음으로, 가장 중요했던 텍스트 가독성 문제를 해결할 차례였다. prose와 Toast UI의 다크 모드 클래스를 조합한, 누구보다 강력한 선택자를 만들어냈다.

/* globals.css */
.prose.toastui-editor-dark {
  --tw-prose-body: theme('colors.gray.300');
  --tw-prose-headings: theme('colors.gray.100');
  --tw-prose-links: theme('colors.blue.400');
  /* ... 등등 */
}

이 코드는 Tailwind Typography의 공식적인 다크 모드 오버라이드 방식이다. .prose와 .toastui-editor-dark 클래스가 한 요소에 동시에 존재할 때, prose가 사용하는 모든 색상 변수를 내가 원하는 다크 모드용 색상으로 교체하라는 명령이다.

마지막으로, 이 CSS 규칙이 동작할 수 있도록 HTML 구조를 정리했다. MarkdownViewer를 감싸는 부모 컴포넌트인 PostContent가 prose 클래스와 함께 다크 모드일 때 toastui-editor-dark 클래스를 갖도록 책임을 위임했다.

// PostContent.tsx
const articleClassName = `
  prose ...
  ${theme === 'dark' && mounted ? 'toastui-editor-dark' : ''}
`;

return (
  <article className={articleClassName}>
    <MarkdownViewer ... />
  </article>
);

이 마지막 퍼즐 조각이 맞춰지는 순간, 모든 것이 바뀌었다.

벽 너머의 풍경

테마 토글 버튼을 다시 클릭했다. 다크 모드로 전환된 화면에는, 내가 꿈꾸던 모든 것이 완벽하게 구현되어 있었다.

어두운 배경 위로 밝게 빛나는 텍스트, materialDark 스타일을 유지하면서도 명확한 경계를 가진 코드 블록, 모든 것이 완벽한 조화를 이루고 있었다. 길고 험난했던 디버깅 여정의 종착지였다.

이번 경험을 통해 나는 값비싼 교훈을 얻었다. '그냥 안된다'는 것은 없었다. 단지 '아직 내가 모르는 것'이 있을 뿐이었다. 문제 해결의 핵심은 화려한 기술이 아닌, 가설을 세우고, 개발자 도구로 검증하고, 원인을 집요하게 파고드는 가장 기본적인 태도에 있었다.

1부의 마지막, 나는 반드시 이 벽을 넘겠다고 약속했다.

그리고 마침내, 그 약속을 지켰다. 👊

---

에필로그: 빛이 닿지 않던 곳까지, 다크 모드의 완성

가장 큰 산이었던 Editor와 Viewer를 정복하고 나니, 눈앞에 넓은 평원이 펼쳐진 기분이었다. 가장 복잡하고 예측 불가능했던 문제들이 해결된 지금, 남은 작업은 우리가 구축한 견고한 기반 위에 일관된 디자인 원칙을 적용하는, 즐거운 '마무리' 단계였다.

새로운 '골든 룰'의 탄생

복잡한 CSS 오버라이드나 !important와의 전쟁은 끝났다. 이제 우리에게는 모든 것을 해결할 수 있는 단순하고 강력한 규칙, '골든 룰'이 생겼다. 바로 Tailwind CSS의 dark: 접두사였다.

• bg-white가 필요한 곳엔 dark:bg-stone-800을,
• text-gray-800이 필요한 곳엔 dark:text-gray-200을 추가하는 작업.

이 단순한 패턴의 반복만으로 애플리케이션의 모든 구석에 어둠을 내릴 수 있었다.

애플리케이션 전반으로의 확장: 점진적 완성의 즐거움

우리는 체계적인 체크리스트를 만들어, 애플리케이션의 모든 컴포넌트에 다크 모드를 점진적으로 적용해나갔다.

• 글로벌 UI (Footer, PostCard): 가장 먼저 사용자와 마주하는 Footer와 홈페이지의 PostCard부터 시작했다. Header와 PostContent에서 확립한 디자인 언어를 그대로 적용하여 전체적인 통일성을 맞추었다. 로딩 상태를 보여주는 스켈레톤 UI까지 디테일하게 챙기는 것도 잊지 않았다.

• 게시글 상세 페이지의 나머지 조각들: 이미 완성된 본문을 중심으로, PostHeader, PostAuthorProfile 등 주변 UI 요소들의 색상을 조정했다. 이 과정은 마치 잘 짜인 퍼즐의 마지막 조각들을 맞추는 것처럼 즐거웠다.

• 댓글 시스템과 인증 페이지: 사용자의 인터랙션이 가장 활발한 댓글 시스템과 로그인/회원가입 페이지에도 동일한 규칙을 적용했다. 복잡한 상태 변화가 많은 컴포넌트였지만, '골든 룰' 앞에서는 모든 것이 간단했다. 각 폼 요소와 버튼, 안내 메시지에 dark: 접두사를 추가하는 것만으로 모든 작업이 끝났다.

최종 커스터마이징: 나만의 색을 입히다

모든 기능 구현이 끝난 후, 마지막으로 globals.css와 각 컴포넌트에 흩어져 있던 색상 코드들을 내 취향에 맞게 미세 조정하는 시간을 가졌다. 이 과정은 마치 잘 만들어진 자동차의 색상을 고르는 것처럼, 기능에 대한 걱정 없이 순수하게 미적인 부분에만 집중할 수 있는 단계였다.

결론

길고 험난했던 다크 모드 도입 여정은 이렇게 막을 내렸다. 수많은 실패와 디버깅 끝에 얻은 것은 단순히 검은 화면이 아니었다. 라이브러리의 동작 원리를 깊이 이해하고, CSS의 전쟁에서 승리하는 방법을 배웠으며, 무엇보다 어떤 문제든 결국 해결할 수 있다는 자신감을 얻었다.

이제 나의 블로그는 낮에도, 밤에도 사용자를 편안하게 맞이할 준비를 마쳤다.