From e3725eaf66da09b7ca45c1a6f33c4fda1d37d829 Mon Sep 17 00:00:00 2001
From: malloc72p <scra1028@gmail.com>
Date: Tue, 30 Jun 2026 09:49:54 +0900
Subject: [PATCH 1/2] =?UTF-8?q?feat(blog):=20=EB=8B=A4=ED=81=AC=EB=AA=A8?=
 =?UTF-8?q?=EB=93=9C=20=EB=8F=84=EC=9E=85=20=E2=80=94=20=ED=86=A0=ED=81=B0?=
 =?UTF-8?q?=20=EA=B8=B0=EB=B0=98=20=ED=85=8C=EB=A7=88=20=EC=A0=84=ED=99=98?=
 =?UTF-8?q?=20(#90)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- global.css: --color-surface 토큰 + .dark에서 색 변수 오버라이드(텍스트 그레이는
  밝게, 배경 그레이는 어둡게, surface/border/brand/blue). Tailwind v4 유틸이 var()를
  참조하므로 컴포넌트 대부분 변경 없이 전체가 전환됨
- ThemeToggle: html.dark + localStorage 토글, themechange 이벤트 발행
- layout: FOUC 방지 인라인 스크립트(paint 전 테마 결정) + suppressHydrationWarning
- giscus: 사이트 테마 동적 연동(themechange 구독)
- bg-white → bg-surface(5곳): 흰 텍스트(--color-white)와 충돌하던 surface만 토큰화
- e2e/theme: 토글·새로고침 유지 검증

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/blog/e2e/theme.spec.ts                   | 28 ++++++++++
 apps/blog/src/app/global.css                  | 40 +++++++++++++-
 apps/blog/src/app/layout.tsx                  |  9 ++-
 .../blog/src/components/article-container.tsx |  2 +-
 apps/blog/src/components/main-header.tsx      |  4 +-
 apps/blog/src/components/mobile-sidebar.tsx   |  2 +-
 .../post-detail/giscus-comments.tsx           | 17 +++++-
 .../src/components/search/search-modal.tsx    |  4 +-
 apps/blog/src/components/theme-toggle.tsx     | 55 +++++++++++++++++++
 9 files changed, 152 insertions(+), 9 deletions(-)
 create mode 100644 apps/blog/e2e/theme.spec.ts
 create mode 100644 apps/blog/src/components/theme-toggle.tsx

diff --git a/apps/blog/e2e/theme.spec.ts b/apps/blog/e2e/theme.spec.ts
new file mode 100644
index 0000000..164b7ca
--- /dev/null
+++ b/apps/blog/e2e/theme.spec.ts
@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('다크모드', () => {
+  // 기본(시스템) 테마를 light로 고정해 토글 동작을 결정적으로 검증한다.
+  test.use({ colorScheme: 'light' });
+
+  test('테마 토글로 다크모드를 켜고 끌 수 있고, 새로고침 후에도 유지된다', async ({ page }) => {
+    await page.goto('/');
+
+    const html = page.locator('html');
+    const toggle = page.getByRole('button', { name: /모드로 전환/ });
+
+    // 초기에는 라이트(html.dark 없음).
+    await expect(html).not.toHaveClass(/dark/);
+
+    // 토글 → 다크 적용.
+    await toggle.click();
+    await expect(html).toHaveClass(/dark/);
+
+    // 새로고침해도 localStorage로 다크가 유지되어야 한다(FOUC 방지 스크립트).
+    await page.reload();
+    await expect(html).toHaveClass(/dark/);
+
+    // 다시 토글 → 라이트로 복귀.
+    await page.getByRole('button', { name: /모드로 전환/ }).click();
+    await expect(html).not.toHaveClass(/dark/);
+  });
+});
diff --git a/apps/blog/src/app/global.css b/apps/blog/src/app/global.css
index cd70226..a02c873 100644
--- a/apps/blog/src/app/global.css
+++ b/apps/blog/src/app/global.css
@@ -12,16 +12,54 @@
   /* 다크 서피스 단일 토큰. 헤더·드롭다운·사이드바·뱃지의 검정 계열(black/gray-900/950)을 통일한다. */
   --color-ink: #0a0a0a;
   /* 중립 구조색. 값은 기존 Tailwind gray와 동일해 시각 변화 없이 단일 출처로 모은다. */
-  --color-surface-muted: #f9fafb; /* gray-50: 카드 배경 */
+  --color-surface: #ffffff; /* 페이지·카드 기본 배경 */
+  --color-surface-muted: #f9fafb; /* gray-50: 옅은 카드 배경 */
   --color-border: #e5e7eb; /* gray-200: 카드/모달 경계 */
   --color-border-subtle: #f3f4f6; /* gray-100: 옅은 구분선 */
 }
 
+/* === 다크 테마 (#90) ===
+   Tailwind v4 유틸은 var(--color-*)를 참조하므로, html.dark에서 색 변수만 덮어쓰면
+   컴포넌트 변경 없이 전체가 전환된다. 텍스트 그레이(400~900)는 밝게, 배경 그레이(50~200)는
+   어둡게 뒤집는다. 항상 어두운 헤더(ink)·흰 텍스트(text-white)는 별도 토큰이라 그대로 유지된다. */
+.dark {
+  /* 시맨틱 surface */
+  --color-surface: #0f1014;
+  --color-surface-muted: #17181d;
+  /* 배경 그레이(라이트 배경 → 다크) */
+  --color-gray-50: #17181d;
+  --color-gray-100: #1f2026;
+  --color-gray-200: #2a2b32;
+  /* 텍스트 그레이(어두운 글자 → 밝은 글자) */
+  --color-gray-400: #6e7079;
+  --color-gray-500: #8b8d96;
+  --color-gray-600: #a6a8b1;
+  --color-gray-700: #c4c6cd;
+  --color-gray-800: #d9dade;
+  --color-gray-900: #e9eaed;
+  --color-black: #e9eaed; /* text-black → 밝게 */
+  /* 경계 */
+  --color-border: #2a2b32;
+  --color-border-subtle: #232429;
+  /* 브랜드: 다크 배경에서 비텍스트 액센트(포커스 링)는 살짝 밝게 */
+  --color-brand: #818cf8;
+  /* 본문 링크(blue) — 다크에서 밝게 */
+  --color-blue-600: #93b4ff;
+  --color-blue-700: #a8c3ff;
+  --color-blue-800: #c2d5ff;
+}
+
 html,
 body {
   height: 100%;
 }
 
+/* 페이지 전체 배경/기본 글자색을 토큰에 연결해 테마 전환 시 함께 바뀌게 한다. */
+body {
+  background-color: var(--color-surface);
+  color: var(--color-gray-900);
+}
+
 /* 동작 줄이기(prefers-reduced-motion) 설정 시 전역 트랜지션/애니메이션/부드러운 스크롤을 사실상 비활성화한다.
    어지럼증(전정기관 장애) 사용자를 위한 WCAG 2.3.3 대응. */
 @media (prefers-reduced-motion: reduce) {
diff --git a/apps/blog/src/app/layout.tsx b/apps/blog/src/app/layout.tsx
index 2c9fd88..01ec5a8 100644
--- a/apps/blog/src/app/layout.tsx
+++ b/apps/blog/src/app/layout.tsx
@@ -75,9 +75,16 @@ export const metadata = {
  * 폰트 설정 및 공통 메타데이터 설정은 이곳에서 한다.
  */
 export default async function RootLayout({ children }: PropsWithChildren) {
+  // 테마 스크립트가 하이드레이션 전에 html.class를 바꾸므로 suppressHydrationWarning으로 className 불일치 경고를 억제한다.
   return (
-    <html lang="ko">
+    <html lang="ko" suppressHydrationWarning>
       <head>
+        {/* 테마 깜빡임(FOUC) 방지: paint 전에 localStorage/시스템 설정으로 html.dark를 결정한다. */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `try{var t=localStorage.getItem('theme');if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches)){document.documentElement.classList.add('dark')}}catch(e){}`,
+          }}
+        />
         <link rel="icon" type="image/x-icon" href="/favicon.ico"></link>
         {/* <link rel="preconnect" href="https://fonts.googleapis.com" /> */}
         {/* <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" /> */}
diff --git a/apps/blog/src/components/article-container.tsx b/apps/blog/src/components/article-container.tsx
index 31f4e3f..5717486 100644
--- a/apps/blog/src/components/article-container.tsx
+++ b/apps/blog/src/components/article-container.tsx
@@ -12,7 +12,7 @@ export function ArticleContainer({ children, right, jsonLd }: ArticleContainerPr
       // skip 링크(본문 바로가기)의 이동 대상. tabIndex=-1로 프로그램적 포커스를 받을 수 있게 한다.
       id={Constants.a11y.mainContentId}
       tabIndex={-1}
-      className="article-container relative z-10 min-h-[100vh] bg-white flex outline-none"
+      className="article-container relative z-10 min-h-[100vh] bg-surface flex outline-none"
     >
       {jsonLd}
       <div className="grow basis-0 relative"></div>
diff --git a/apps/blog/src/components/main-header.tsx b/apps/blog/src/components/main-header.tsx
index 4a3f6c7..d02dfa5 100644
--- a/apps/blog/src/components/main-header.tsx
+++ b/apps/blog/src/components/main-header.tsx
@@ -5,6 +5,7 @@ import { DropdownMenu } from './dropdown-menu';
 import { SeriesModel, TagModel } from '@libs/types/commons';
 import { MobileSidebar } from './mobile-sidebar';
 import { SearchButton } from './search';
+import { ThemeToggle } from './theme-toggle';
 
 export interface MainHeaderProps {
   seriesList: SeriesModel[];
@@ -26,7 +27,8 @@ export function MainHeader({ seriesList, tags }: MainHeaderProps) {
 
         <span className="grow"></span>
 
-        {/* === SEARCH BUTTON (모든 화면 크기에서 노출) === */}
+        {/* === 테마 토글 + 검색 (모든 화면 크기에서 노출) === */}
+        <ThemeToggle className="text-white" />
         <SearchButton className="mr-5 text-white" />
 
         {/* === HEADER >= MD: RIGHT SECTION === */}
diff --git a/apps/blog/src/components/mobile-sidebar.tsx b/apps/blog/src/components/mobile-sidebar.tsx
index 97af953..ae8689d 100644
--- a/apps/blog/src/components/mobile-sidebar.tsx
+++ b/apps/blog/src/components/mobile-sidebar.tsx
@@ -118,7 +118,7 @@ export function MobileSidebar({ seriesList, tags }: MobileSidebarProps) {
         className={classNames(
           // 모바일 브라우저 주소창 높이를 반영하도록 100vh 대신 100dvh를 사용한다.
           // md:hidden — 데스크톱 너비에서는 패널이 열린 채 남지 않도록 숨긴다.
-          'h-[100dvh] w-full bg-white z-50 fixed top-0 right-0 md:hidden',
+          'h-[100dvh] w-full bg-surface z-50 fixed top-0 right-0 md:hidden',
           // 헤더는 고정하고 콘텐츠 영역만 스크롤시키기 위해 세로 flex 컬럼으로 구성한다.
           'flex flex-col',
           // 전이는 가로 슬라이드(transform)로 한정한다. transition-all이면 dvh 높이 변화까지
diff --git a/apps/blog/src/components/post-detail/giscus-comments.tsx b/apps/blog/src/components/post-detail/giscus-comments.tsx
index 79c8093..028032d 100644
--- a/apps/blog/src/components/post-detail/giscus-comments.tsx
+++ b/apps/blog/src/components/post-detail/giscus-comments.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import Giscus from '@giscus/react';
+import { useEffect, useState } from 'react';
 
 /**
  * GitHub Discussions 기반 댓글 위젯(giscus).
@@ -12,6 +13,18 @@ import Giscus from '@giscus/react';
  * 동작에는 저장소에 giscus GitHub App 설치가 필요하다(앱 설치는 저장소 소유자만 가능).
  */
 export function GiscusComments() {
+  // 사이트 테마(html.dark)를 따라가도록 한다. ThemeToggle이 보내는 themechange 이벤트로 갱신한다.
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+
+  useEffect(() => {
+    setTheme(document.documentElement.classList.contains('dark') ? 'dark' : 'light');
+    const onChange = (e: Event) => {
+      setTheme((e as CustomEvent<string>).detail === 'dark' ? 'dark' : 'light');
+    };
+    window.addEventListener('themechange', onChange);
+    return () => window.removeEventListener('themechange', onChange);
+  }, []);
+
   return (
     <Giscus
       // 댓글이 저장될 저장소와 그 GraphQL 노드 ID
@@ -28,8 +41,8 @@ export function GiscusComments() {
       emitMetadata="0"
       // 입력창을 댓글 목록 아래에 배치
       inputPosition="bottom"
-      // 블로그가 라이트 테마라 라이트로 고정
-      theme="light"
+      // 사이트 테마(라이트/다크)를 따라간다
+      theme={theme}
       lang="ko"
       // 뷰포트에 들어올 때 로드해 초기 렌더 비용을 줄인다
       loading="lazy"
diff --git a/apps/blog/src/components/search/search-modal.tsx b/apps/blog/src/components/search/search-modal.tsx
index 5eb4038..e319dda 100644
--- a/apps/blog/src/components/search/search-modal.tsx
+++ b/apps/blog/src/components/search/search-modal.tsx
@@ -102,7 +102,7 @@ export function SearchModal() {
         role="dialog"
         aria-modal="true"
         aria-label="포스트 검색"
-        className="w-full max-w-[640px] overflow-hidden rounded-xl bg-white shadow-2xl"
+        className="w-full max-w-[640px] overflow-hidden rounded-xl bg-surface shadow-2xl"
         onClick={(e) => e.stopPropagation()}
         onKeyDown={onKeyDown}
       >
@@ -166,7 +166,7 @@ export function SearchModal() {
                   onMouseEnter={() => setActiveIndex(idx)}
                   className={classNames(
                     'block border-b border-border-subtle px-4 py-3',
-                    idx === activeIndex ? 'bg-gray-100' : 'bg-white',
+                    idx === activeIndex ? 'bg-gray-100' : 'bg-surface',
                   )}
                 >
                   <div className="flex items-center gap-2">
diff --git a/apps/blog/src/components/theme-toggle.tsx b/apps/blog/src/components/theme-toggle.tsx
new file mode 100644
index 0000000..2f80dcc
--- /dev/null
+++ b/apps/blog/src/components/theme-toggle.tsx
@@ -0,0 +1,55 @@
+'use client';
+
+import { IconMoon, IconSun } from '@tabler/icons-react';
+import classNames from 'classnames';
+import { useEffect, useState } from 'react';
+
+interface ThemeToggleProps {
+  className?: string;
+}
+
+/**
+ * 라이트/다크 테마 전환 버튼.
+ *
+ * html.dark 클래스와 localStorage를 직접 토글한다. 초기 클래스는 layout <head>의
+ * 인라인 스크립트가 paint 전에 설정하므로(FOUC 방지), 이 컴포넌트는 마운트 후
+ * 현재 상태를 읽어 아이콘만 맞춘다.
+ */
+export function ThemeToggle({ className }: ThemeToggleProps) {
+  const [dark, setDark] = useState(false);
+
+  useEffect(() => {
+    // 서버/첫 렌더는 light로 그리고, 마운트 후 실제 html.dark 상태로 보정한다.
+    setDark(document.documentElement.classList.contains('dark'));
+  }, []);
+
+  const toggle = () => {
+    const next = !dark;
+    setDark(next);
+    document.documentElement.classList.toggle('dark', next);
+    try {
+      localStorage.setItem('theme', next ? 'dark' : 'light');
+    } catch {
+      // 프라이빗 모드 등 localStorage 접근이 막힌 환경은 조용히 무시한다.
+    }
+    // giscus 등 외부 위젯이 테마를 따라오도록 전역 이벤트로 알린다.
+    window.dispatchEvent(new CustomEvent('themechange', { detail: next ? 'dark' : 'light' }));
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-label={dark ? '라이트 모드로 전환' : '다크 모드로 전환'}
+      className={classNames(
+        // 아이콘(20px)에 패딩을 더해 탭 영역을 ~44px로 확보한다.
+        'flex cursor-pointer items-center p-2.5',
+        // 다크 헤더 위에서 키보드 포커스가 보이도록 밝은 outline + offset을 부여한다.
+        'focus-visible:outline focus-visible:outline-2 focus-visible:outline-white focus-visible:outline-offset-2',
+        className,
+      )}
+    >
+      {dark ? <IconSun className="h-5 w-5" /> : <IconMoon className="h-5 w-5" />}
+    </button>
+  );
+}

From c714d72588027d76b7034a8edfd04bd6157bc5cd Mon Sep 17 00:00:00 2001
From: malloc72p <scra1028@gmail.com>
Date: Tue, 30 Jun 2026 09:53:18 +0900
Subject: [PATCH 2/2] =?UTF-8?q?fix(blog):=20=EB=A6=AC=EB=B7=B0=20=EB=B0=98?=
 =?UTF-8?q?=EC=98=81=20=E2=80=94=20=ED=85=8C=EB=A7=88=20=ED=86=A0=EA=B8=80?=
 =?UTF-8?q?=20=EC=95=84=EC=9D=B4=EC=BD=98=20=ED=94=8C=EB=9E=98=EC=8B=9C=20?=
 =?UTF-8?q?=EC=A0=9C=EA=B1=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- global.css: @custom-variant dark로 dark: 유틸이 .dark 클래스를 따르게 설정
- ThemeToggle 아이콘을 JS 상태 대신 CSS(dark:)로 토글 → 다크로 로드된 페이지에서
  첫 프레임부터 해/달 아이콘이 html.dark와 일치(플래시 없음). aria-label만 상태 유지

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/blog/src/app/global.css              | 3 +++
 apps/blog/src/components/theme-toggle.tsx | 9 ++++++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/apps/blog/src/app/global.css b/apps/blog/src/app/global.css
index a02c873..20d7e23 100644
--- a/apps/blog/src/app/global.css
+++ b/apps/blog/src/app/global.css
@@ -1,5 +1,8 @@
 @import 'tailwindcss';
 
+/* dark: 유틸리티가 OS 설정이 아니라 html.dark 클래스를 따르게 한다(클래스 기반 테마 토글). */
+@custom-variant dark (&:where(.dark, .dark *));
+
 /* === 디자인 토큰 (#94, #120) ===
    Tailwind v4 @theme로 의미 기반 색 토큰을 정의한다. 각 토큰은 bg-brand/text-ink/
    border-border 등 깔끔한 유틸리티로 생성되며, :root에 CSS 변수로도 노출된다.
diff --git a/apps/blog/src/components/theme-toggle.tsx b/apps/blog/src/components/theme-toggle.tsx
index 2f80dcc..9009526 100644
--- a/apps/blog/src/components/theme-toggle.tsx
+++ b/apps/blog/src/components/theme-toggle.tsx
@@ -16,15 +16,16 @@ interface ThemeToggleProps {
  * 현재 상태를 읽어 아이콘만 맞춘다.
  */
 export function ThemeToggle({ className }: ThemeToggleProps) {
+  // aria-label(스크린리더 전용)만 상태로 관리한다. 보이는 아이콘은 아래 CSS(dark:)로 토글해
+  // 첫 프레임부터 html.dark와 일치시킨다(아이콘 플래시 없음).
   const [dark, setDark] = useState(false);
 
   useEffect(() => {
-    // 서버/첫 렌더는 light로 그리고, 마운트 후 실제 html.dark 상태로 보정한다.
     setDark(document.documentElement.classList.contains('dark'));
   }, []);
 
   const toggle = () => {
-    const next = !dark;
+    const next = !document.documentElement.classList.contains('dark');
     setDark(next);
     document.documentElement.classList.toggle('dark', next);
     try {
@@ -49,7 +50,9 @@ export function ThemeToggle({ className }: ThemeToggleProps) {
         className,
       )}
     >
-      {dark ? <IconSun className="h-5 w-5" /> : <IconMoon className="h-5 w-5" />}
+      {/* 라이트일 때 달(다크로 전환), 다크일 때 해(라이트로 전환). html.dark 클래스로 CSS 토글. */}
+      <IconMoon aria-hidden className="h-5 w-5 block dark:hidden" />
+      <IconSun aria-hidden className="h-5 w-5 hidden dark:block" />
     </button>
   );
 }