Files

T

Antigravity Agent 504fd5fb42 [G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00

7.5 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

title

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

매 한 줄

"매 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

Primitive tokens: --color-blue-500: oklch(60% 0.2 240).
Semantic tokens: --color-bg-primary (theme-aware).
Component tokens: --button-bg = --color-action.
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).

매 응용

GitHub 의 light/light-high-contrast/dark/dark-dimmed/dark-high-contrast 의 5 modes.
Stripe Dashboard 의 brand switcher (Atlas, Climate 등).
Linear 의 theme + accent color picker.
VS Code 의 theme marketplace (color-theme JSON).

💻 패턴

1. CSS `light-dark()` (2026 baseline)

: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

: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)

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 스타일)

'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

'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

/* 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));
}

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

7. Image / asset variants (theme-aware)

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)

async function toggleTheme(next: 'light' | 'dark') {
  if (!document.startViewTransition) {
    document.documentElement.dataset.theme = next;
    return;
  }
  await document.startViewTransition(() => {
    document.documentElement.dataset.theme = next;
  }).ready;
}

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

// 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 · White_Label_Architecture
응용: Tailwind_v4 · Styled_Components_v6 · CSS_Modules
Adjacent: Accessibility_Color_Contrast · OKLCH_Color · 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

7.5 KiB Raw Blame History Unescape Escape