chore(brain): ASTRA 성장 자산 동기화 — 기능 인벤토리·growth(약점프로필/학습큐)·일화기억·장기기억·회의록 원문

2026-06-12 16:37:41 +09:00
parent a97fc7be07
commit 89fb05a28a
781 changed files with 138546 additions and 47 deletions
@@ -0,0 +1,247 @@
+---
+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 |