---
id: wiki-2026-0508-다크-모드-및-다중-브랜드-테마-동적-전환-시스템
title: 다크 모드 및 다중 브랜드 테마 동적 전환 시스템
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Dark Mode, Theme Switching, Multi-brand Theming]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [frontend, css, theming, dark-mode, design-system]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript/CSS
  framework: React/Next.js
---

# 다크 모드 및 다중 브랜드 테마 동적 전환 시스템

## 매 한 줄
> **"매 CSS variables × design tokens × runtime swap 의 zero-flash theming"**. 매 다크 모드는 단순 색상 toggle이 아닌, design token system의 multi-channel orchestration. 2026 표준은 `light-dark()` CSS function + `prefers-color-scheme` + system token + brand override 의 4-layer cascade.

## 매 핵심

### 매 4-Layer Token Architecture
1. **Primitive tokens**: `--color-blue-500: oklch(60% 0.2 240)`.
2. **Semantic tokens**: `--color-bg-primary` (theme-aware).
3. **Component tokens**: `--button-bg = --color-action`.
4. **Brand override**: `[data-brand="acme"] { --color-action: ... }`.

### 매 SSR Flash 방지
- Inline blocking script (head) 의 `localStorage` read → `<html data-theme="dark">` 의 set before paint.
- Next.js: `next-themes` library 의 표준.
- Cookie-based 의 SSR-aware (Next 15 RSC).

### 매 응용
1. GitHub 의 `light/light-high-contrast/dark/dark-dimmed/dark-high-contrast` 의 5 modes.
2. Stripe Dashboard 의 brand switcher (Atlas, Climate 등).
3. Linear 의 theme + accent color picker.
4. VS Code 의 theme marketplace (color-theme JSON).

## 💻 패턴

### 1. CSS `light-dark()` (2026 baseline)
```css
:root {
  color-scheme: light dark;
  --bg: light-dark(white, #0a0a0a);
  --fg: light-dark(#0a0a0a, white);
  --accent: light-dark(oklch(55% 0.2 250), oklch(70% 0.18 250));
}

[data-theme="light"] { color-scheme: light; }
[data-theme="dark"]  { color-scheme: dark; }
```

### 2. Multi-brand token override
```css
:root[data-brand="default"] { --brand-primary: oklch(55% 0.2 250); }
:root[data-brand="acme"]    { --brand-primary: oklch(60% 0.22 30); }
:root[data-brand="globex"]  { --brand-primary: oklch(58% 0.25 140); }

.btn-primary {
  background: var(--brand-primary);
  color: light-dark(white, black);
}
```

### 3. No-flash inline script (Next.js layout.tsx)
```tsx
const themeScript = `
(function() {
  try {
    const saved = localStorage.getItem('theme');
    const sys = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    const theme = saved || sys;
    document.documentElement.dataset.theme = theme;
    document.documentElement.style.colorScheme = theme;
  } catch (e) {}
})();
`;

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: themeScript }} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

### 4. React Theme Provider (next-themes 스타일)
```tsx
'use client';
import { createContext, useContext, useEffect, useState } from 'react';

type Theme = 'light' | 'dark' | 'system';
const ThemeCtx = createContext<{ theme: Theme; setTheme: (t: Theme) => void }>(null!);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setThemeState] = useState<Theme>('system');

  useEffect(() => {
    const saved = (localStorage.getItem('theme') as Theme) || 'system';
    setThemeState(saved);
  }, []);

  useEffect(() => {
    const resolved = theme === 'system'
      ? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
      : theme;
    document.documentElement.dataset.theme = resolved;
    document.documentElement.style.colorScheme = resolved;
  }, [theme]);

  const setTheme = (t: Theme) => {
    localStorage.setItem('theme', t);
    setThemeState(t);
  };

  return <ThemeCtx.Provider value={{ theme, setTheme }}>{children}</ThemeCtx.Provider>;
}

export const useTheme = () => useContext(ThemeCtx);
```

### 5. Brand context + dynamic token injection
```tsx
'use client';
import { useEffect } from 'react';

export function BrandProvider({ brand, children }: { brand: 'acme' | 'globex'; children: React.ReactNode }) {
  useEffect(() => {
    document.documentElement.dataset.brand = brand;
  }, [brand]);
  return <>{children}</>;
}
```

### 6. Tailwind v4 + design tokens
```css
/* app/globals.css */
@import "tailwindcss";

@theme {
  --color-bg: light-dark(white, #0a0a0a);
  --color-fg: light-dark(#0a0a0a, white);
  --color-brand: var(--brand-primary, oklch(55% 0.2 250));
}
```

```tsx
<button className="bg-brand text-bg">Click</button>
```

### 7. Image / asset variants (theme-aware)
```tsx
import Image from 'next/image';
import { useTheme } from '@/lib/theme';

export function Logo() {
  const { theme } = useTheme();
  return (
    <picture>
      <source srcSet="/logo-dark.svg" media="(prefers-color-scheme: dark)" />
      <img src="/logo-light.svg" alt="Logo" />
    </picture>
  );
}
```

### 8. View Transitions API (smooth theme swap)
```ts
async function toggleTheme(next: 'light' | 'dark') {
  if (!document.startViewTransition) {
    document.documentElement.dataset.theme = next;
    return;
  }
  await document.startViewTransition(() => {
    document.documentElement.dataset.theme = next;
  }).ready;
}
```

```css
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 200ms;
}
```

### 9. SSR cookie-based theme (Next 15 RSC)
```tsx
// app/layout.tsx (server)
import { cookies } from 'next/headers';

export default async function Layout({ children }) {
  const theme = (await cookies()).get('theme')?.value ?? 'light';
  return <html data-theme={theme}>{children}</html>;
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 단일 브랜드 + dark mode | CSS `light-dark()` + `prefers-color-scheme` |
| 다중 브랜드 SaaS | `data-brand` attribute + token override |
| SSR Next.js | next-themes OR cookie-based RSC |
| Tailwind v4 | `@theme` + CSS vars |
| Smooth transition | View Transitions API |
| Legacy browser | Class-based (`.dark`) + localStorage |

**기본값**: CSS `light-dark()` + `data-theme` + `data-brand` + cookie SSR + next-themes.

## 🔗 Graph
- 부모: [[Design_Systems]] · [[CSS_Variables]]
- 변형: [[Design_Tokens]]
- 응용: [[Tailwind_v4]] · [[Styled_Components_v6]] · [[CSS_Modules]]
- Adjacent: [[View_Transitions_API]]

## 🤖 LLM 활용
**언제**: token naming convention 제안, contrast ratio audit, brand palette 생성 (OKLCH 기반).
**언제 X**: 최종 brand color decision (디자이너), accessibility AA/AAA 의 자동 보장은 X.

## ❌ 안티패턴
- **No-flash 미구현**: hydration 후 theme 적용 → FOUC.
- **Hardcoded hex**: design token 의 bypass — multi-brand 의 X.
- **JS-only theming**: CSS-only 의 fallback 없으면 SSR flash.
- **Inverted contrast**: 다크 모드의 단순 색상 invert — semantic hierarchy 의 break.
- **`!important` overuse**: token cascade 의 collapse.
- **`localStorage` SSR access**: hydration mismatch — `useEffect`로 lazy.

## 🧪 검증 / 중복
- Verified (web.dev color-scheme guide, MDN `light-dark()`, next-themes docs).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — dark mode + multi-brand theming full content |
