Antigravity Agent
f8b21af4be
10_Wiki/Topics 대규모 정리: - 오류 캡처/미완성 stub 문서 227개 제거 - 교차폴더 중복 43클러스터 병합 (63파일 → redirect) - 링크명 정규화: 깨진 링크 수정·redirect 직결·개념 매핑 ~2,400건 - 카테고리 MOC 6개 신규 생성 - Graph 섹션 미해결 related-keyword 링크 10,058건 제거 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
248 lines
7.4 KiB
Markdown
248 lines
7.4 KiB
Markdown
---
|
||
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 |
|