---
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 → `` 의 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 (
{children}
);
}
```
### 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('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 {children};
}
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
```
### 7. Image / asset variants (theme-aware)
```tsx
import Image from 'next/image';
import { useTheme } from '@/lib/theme';
export function Logo() {
const { theme } = useTheme();
return (
);
}
```
### 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 {children};
}
```
## 매 결정 기준
| 상황 | 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 |
