O Caso de Uso Mais Puro para Context

O gerenciamento de temas é um dos casos de uso mais puros para context. Um tema afeta cada componente visual em uma aplicação, precisa mudar dinamicamente e não deve exigir prop drilling por dezenas de componentes. O Context oferece exatamente o que o tema precisa: dados ambientais que qualquer descendente pode acessar sem fiação explícita.

Se você não precisa de substituições de tema aninhadas — diferentes partes da árvore de componentes usando temas diferentes simultaneamente — considere o padrão mais simples do hook useTheme. Ele usa estado reativo no nível do módulo, não requer providers e cobre 95% dos casos de uso em menos de 100 linhas de código. Este artigo aborda a abordagem com Context para quando você especificamente precisa de providers aninhados.

Ao final deste artigo, você terá um sistema de temas que suporta modos claro, escuro e de preferência do sistema, detecta e responde automaticamente a mudanças de tema do sistema operacional, persiste as preferências do usuário no localStorage, carrega sem nenhum "flash de tema errado", funciona corretamente com renderização no lado do servidor e suporta substituições locais de tema por meio de providers aninhados.

O insight arquitetural central: o CSS é a única fonte de verdade para as cores. O JavaScript apenas gerencia qual tema está ativo definindo o atributo data-theme. O navegador cuida do resto de forma nativa e eficiente.

O Espaço do Problema

Antes de escrever código, considere o que torna o tema genuinamente difícil. A abordagem óbvia — passar uma prop theme por cada componente — falha imediatamente em qualquer aplicação real. Com navegação, sidebars, cards, botões, formulários, modais e tooltips todos precisando de informações de tema, você estaria passando a mesma prop por cada componente da sua árvore.

O Context resolve o problema de distribuição, mas o tema tem complicações adicionais. Primeiro, há a distinção entre preferência e resolução. Quando um usuário seleciona "sistema" como preferência de tema, os componentes precisam de um tema real — claro ou escuro — para renderizar. Algo deve resolver a preferência em um tema concreto.

Segundo, a preferência do sistema não é estática. Os usuários mudam o tema do sistema enquanto seu app está em execução. Seu sistema de temas deve escutar essas mudanças e responder em tempo real.

Terceiro, a renderização no lado do servidor cria um problema de temporização. O servidor renderiza HTML sem saber a preferência do usuário. Quando o JavaScript carrega e lê o localStorage, o navegador já pintou a página com o tema errado. Os usuários veem um flash perturbador.

Quarto, substituições aninhadas são um requisito legítimo. Um card promocional com tema escuro em uma página clara exige que diferentes partes da árvore de componentes usem temas diferentes simultaneamente. Este é o principal motivo para usar Context em vez de estado no nível do módulo.

O Que Faz um Bom Sistema de Temas?

Antes de mergulhar na implementação, vamos estabelecer requisitos claros. Um sistema de temas de qualidade para produção deve atender a estes critérios:

Requisitos Funcionais

Requisito	Descrição
Múltiplos modos	Suportar pelo menos temas claro e escuro
Preferência do sistema	Detectar a preferência de esquema de cores do SO
Substituição do usuário	Permitir que usuários escolham seu tema preferido
Persistência	Lembrar a escolha do usuário entre sessões
Sincronização em tempo real	Responder quando a preferência do sistema muda
Acesso fácil do componente	API simples para qualquer componente ler o tema

Requisitos de Experiência do Usuário

Requisito	Descrição
Sem flash	A página carrega com o tema correto imediatamente
Transições suaves	Mudanças de tema são animadas graciosamente
Consistente	Todos os componentes refletem o tema simultaneamente
Acessível	Controles de tema possuem atributos ARIA adequados

Requisitos de Experiência do Desenvolvedor

Requisito	Descrição
Type-safe	Suporte completo a TypeScript com inferência
Encapsulado	Detalhes de implementação ocultos dos consumidores
Composável	Funciona com variáveis CSS, Tailwind ou acesso direto
Compatível com SSR	Funciona com a renderização no servidor do SvelteKit

Com esses requisitos em mente, vamos projetar nossa solução.

Visão Geral da Arquitetura de Temas

O insight central: o CSS cuida de todas as definições de cores e da troca. O único trabalho do JavaScript é definir o atributo data-theme. Isso é mais simples, mais rápido e é o que todas as bibliotecas de produção utilizam.

O Modelo de Três Modos

A maioria das aplicações precisa de três configurações de tema: Claro (sempre usar tema claro), Escuro (sempre usar tema escuro) e Sistema (seguir a preferência do sistema operacional).

Os componentes nunca lidam com o caso 'system' por si mesmos — eles sempre recebem um 'light' ou 'dark' definitivo.

CSS: A Única Fonte de Verdade

Defina todas as cores do tema no seu CSS global. Este é o único lugar onde as cores são definidas:

/* src/app.css */

/* Light theme (default) */
:root {
	--color-background: #ffffff;
	--color-surface: #f8fafc;
	--color-surface-hover: #f1f5f9;
	--color-foreground: #0f172a;
	--color-foreground-muted: #475569;
	--color-foreground-subtle: #94a3b8;
	--color-primary: #2563eb;
	--color-primary-hover: #1d4ed8;
	--color-primary-foreground: #ffffff;
	--color-success: #16a34a;
	--color-warning: #ca8a04;
	--color-error: #dc2626;
	--color-info: #0284c7;
	--color-border: #e2e8f0;
	--color-border-focus: #3b82f6;
	--color-shadow: rgba(0, 0, 0, 0.1);
}

/* Dark theme */
:root[data-theme='dark'] {
	--color-background: #0f172a;
	--color-surface: #1e293b;
	--color-surface-hover: #334155;
	--color-foreground: #f8fafc;
	--color-foreground-muted: #cbd5e1;
	--color-foreground-subtle: #64748b;
	--color-primary: #3b82f6;
	--color-primary-hover: #60a5fa;
	--color-primary-foreground: #ffffff;
	--color-success: #22c55e;
	--color-warning: #eab308;
	--color-error: #ef4444;
	--color-info: #0ea5e9;
	--color-border: #334155;
	--color-border-focus: #60a5fa;
	--color-shadow: rgba(0, 0, 0, 0.4);
}

/* Base styles */
html,
body {
	margin: 0;
	background-color: var(--color-background);
	color: var(--color-foreground);
	font-family:
		system-ui,
		-apple-system,
		sans-serif;
	line-height: 1.5;
	transition:
		background-color 0.3s ease,
		color 0.3s ease;
}

Única fonte de verdade — Cores definidas uma vez, sem duplicação em objetos TypeScript.

Desempenho nativo do navegador — O navegador lida com a troca de variáveis CSS nativamente — sem loops JavaScript ou chamadas setProperty.

Amigável ao DevTools — Veja todas as variáveis no painel Styles, fácil de depurar.

Funciona antes do JavaScript — Com SSR adequado, os temas funcionam mesmo se o JS falhar ao carregar.

Quando Propriedades CSS Baseadas em JavaScript SÃO Necessárias

A abordagem CSS-first funciona para 95% das aplicações. No entanto, há casos legítimos em que você precisa que o JavaScript defina propriedades CSS customizadas dinamicamente:

Caso de Uso	Por Que JavaScript É Necessário
Cores personalizáveis pelo usuário	Color picker onde usuários escolhem sua própria paleta — as cores não são conhecidas em tempo de build
Temas orientados por API	Cores obtidas de banco de dados, CMS ou sistema de gerenciamento de marca
Computação em runtime	Geração de tints, sombras ou escalas de cores programaticamente (ex.: `chroma.js`)
Integração com terceiros	Bibliotecas que precisam de valores de cor em JS (Chart.js, D3, Canvas APIs)
Produtos white-label	Apps SaaS onde cada tenant possui branding personalizado carregado em runtime

Se as cores são conhecidas em tempo de build → Defina-as no CSS.

Se as cores são determinadas em runtime → Use JavaScript para defini-las.

A maioria dos apps tem paletas de cores estáticas, então CSS-first é a escolha padrão.

Para implementações detalhadas de cada caso de uso — incluindo color pickers, temas orientados por API, geração de paletas com Chroma.js, integração com Chart.js e padrões SaaS white-label — veja o artigo dedicado: Personalização Dinâmica de Temas: Propriedades CSS em Runtime.

Construindo o Theme Context

Agora vamos construir o context. Observe como é simples — o JavaScript apenas gerencia o estado e define o atributo data-theme:

// src/lib/theme/types.ts

/** User-facing theme options */
export type ThemePreference = 'light' | 'dark' | 'system'

/** Actual rendered theme after resolving 'system' */
export type ResolvedTheme = 'light' | 'dark'

/** Theme context shape exposed to consumers */
export interface ThemeContext {
	readonly mode: ResolvedTheme
	readonly preference: ThemePreference
	readonly isDark: boolean
	readonly isLight: boolean
	readonly isSystem: boolean
	setPreference: (theme: ThemePreference) => void
	toggle: () => void
	reset: () => void
}

// src/lib/theme/theme-context.svelte.ts

import { setContext, getContext, hasContext } from 'svelte'
import { browser } from '$app/environment'
import type { ThemePreference, ResolvedTheme, ThemeContext } from './types.js'

const THEME_KEY = Symbol('theme')
const STORAGE_KEY = 'theme-preference'
const COOKIE_MAX_AGE = 60 * 60 * 24 * 365 // 1 year

function getSystemPreference(): ResolvedTheme {
	if (!browser) return 'light'
	return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
}

function loadSavedPreference(): ThemePreference | null {
	if (!browser) return null
	const saved = localStorage.getItem(STORAGE_KEY)
	if (saved === 'light' || saved === 'dark' || saved === 'system') {
		return saved
	}
	return null
}

interface CreateThemeOptions {
	/** Force a specific theme (for nested overrides) */
	forceTheme?: ResolvedTheme
}

/**
 * Creates the theme context. Call once in root layout,
 * or nested for local theme overrides.
 */
export function createThemeContext(options: CreateThemeOptions = {}): ThemeContext {
	const { forceTheme } = options

	// State
	let systemMode = $state<ResolvedTheme>(getSystemPreference())
	let preference = $state<ThemePreference>(loadSavedPreference() ?? 'system')

	// Derived values
	let mode = $derived.by<ResolvedTheme>(() => {
		if (forceTheme) return forceTheme
		if (preference === 'system') return systemMode
		return preference
	})

	let isDark = $derived(mode === 'dark')
	let isLight = $derived(mode === 'light')
	let isSystem = $derived(preference === 'system')

	// Effect: Listen for system preference changes
	$effect(() => {
		if (!browser) return

		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')

		function handleChange(event: MediaQueryListEvent) {
			systemMode = event.matches ? 'dark' : 'light'
		}

		systemMode = mediaQuery.matches ? 'dark' : 'light'
		mediaQuery.addEventListener('change', handleChange)

		return () => mediaQuery.removeEventListener('change', handleChange)
	})

	// Effect: Apply theme (skip for nested providers)
	$effect(() => {
		if (!browser || forceTheme) return

		// This is ALL JavaScript needs to do!
		document.documentElement.dataset.theme = mode
		document.documentElement.style.colorScheme = mode
	})

	// Effect: Persist preference (skip for nested providers)
	$effect(() => {
		if (!browser || forceTheme) return

		localStorage.setItem(STORAGE_KEY, preference)
		document.cookie = `${STORAGE_KEY}=${preference};path=/;max-age=${COOKIE_MAX_AGE};SameSite=Lax`
	})

	// Effect: Update meta theme-color for mobile browsers
	$effect(() => {
		if (!browser || forceTheme) return

		let meta = document.querySelector('meta[name="theme-color"]')
		if (!meta) {
			meta = document.createElement('meta')
			meta.setAttribute('name', 'theme-color')
			document.head.appendChild(meta)
		}

		// Read the CSS variable value
		const bg = getComputedStyle(document.documentElement)
			.getPropertyValue('--color-background')
			.trim()
		meta.setAttribute('content', bg)
	})

	// Build context with getters for reactivity
	const context: ThemeContext = {
		get mode() {
			return mode
		},
		get preference() {
			return preference
		},
		get isDark() {
			return isDark
		},
		get isLight() {
			return isLight
		},
		get isSystem() {
			return isSystem
		},

		setPreference(pref: ThemePreference) {
			preference = pref
		},

		toggle() {
			if (preference === 'system') {
				preference = mode === 'dark' ? 'light' : 'dark'
			} else {
				preference = preference === 'dark' ? 'light' : 'dark'
			}
		},

		reset() {
			preference = 'system'
		}
	}

	return setContext(THEME_KEY, context)
}

export function getThemeContext(): ThemeContext {
	if (!hasContext(THEME_KEY)) {
		throw new Error('Theme context not found. Wrap your app in ThemeProvider.')
	}
	return getContext(THEME_KEY)
}

export function hasThemeContext(): boolean {
	return hasContext(THEME_KEY)
}

Observe o que não está aqui:

Sem tipo ThemeColors
Sem objetos lightColors / darkColors
Sem função applyCSSProperties
Sem loops definindo propriedades CSS

O JavaScript apenas define data-theme e o CSS cuida de todo o resto.

Criando o Componente Provider

<!-- src/lib/theme/ThemeProvider.svelte -->
<script lang="ts">
	import { createThemeContext } from './theme-context.svelte.js'
	import type { ResolvedTheme } from './types.js'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Force a specific theme (for nested overrides) */
		forceTheme?: ResolvedTheme
		children: Snippet
	}

	let { forceTheme, children }: Props = $props()

	const theme = createThemeContext({ forceTheme })
</script>

<!-- For nested providers, set data-theme on the wrapper -->
{#if forceTheme}
	<div class="theme-scope" data-theme={theme.mode}>
		{@render children()}
	</div>
{:else}
	{@render children()}
{/if}

<style>
	.theme-scope {
		background-color: var(--color-background);
		color: var(--color-foreground);
		transition:
			background-color 0.3s ease,
			color 0.3s ease;
	}
</style>

Usando o Provider

<!-- src/routes/+layout.svelte -->
<script>
	import ThemeProvider from '$lib/theme/ThemeProvider.svelte'
	import '../app.css'

	let { children } = $props()
</script>

<ThemeProvider>
	{@render children()}
</ThemeProvider>

Substituições de Tema Aninhadas

Este é o principal motivo para usar Context em vez de estado no nível do módulo. O escopo do Context permite providers aninhados:

<!-- src/routes/+page.svelte -->
<script>
	import ThemeProvider from '$lib/theme/ThemeProvider.svelte'
</script>

<!-- Page uses global theme (light) -->
<div class="page">
	<h1>Welcome</h1>

	<!-- This section forces dark theme -->
	<ThemeProvider forceTheme="dark">
		<section class="promo-card">
			<h2>Featured Content</h2>
			<p>This card is always dark, even on a light page.</p>
		</section>
	</ThemeProvider>

	<!-- This follows the page theme -->
	<section class="regular-card">
		<h2>Regular Content</h2>
		<p>This card follows the page theme.</p>
	</section>
</div>

<style>
	.promo-card,
	.regular-card {
		background-color: var(--color-surface);
		color: var(--color-foreground);
		border: 1px solid var(--color-border);
		padding: 1.5rem;
		border-radius: 12px;
		margin: 1rem 0;
	}
</style>

O ThemeProvider aninhado define data-theme="dark" em seu div wrapper. As propriedades CSS customizadas fazem cascata, portanto tudo dentro usa cores escuras enquanto tudo fora permanece claro.

Prevenindo o Flash de Tema Errado

No servidor, não temos localStorage ou matchMedia. O tema vai piscar ao se corrigir durante a hidratação. Para corrigir isso, podemos adicionar um script inline ao cabeçalho do app.html que é executado antes da página renderizar, definindo o tema correto imediatamente:

<!-- src/app.html -->
<!doctype html>
<html lang="en" data-theme="">
	<head>
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />

		<!-- CRITICAL: Runs before page renders -->
		<script>
			;(function () {
				try {
					const stored = localStorage.getItem('theme-preference')
					const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches

					let theme
					if (stored === 'dark' || stored === 'light') {
						theme = stored
					} else {
						theme = systemDark ? 'dark' : 'light'
					}

					document.documentElement.dataset.theme = theme
					document.documentElement.style.colorScheme = theme
				} catch (e) {
					// localStorage might be blocked
				}
			})()
		</script>

		%sveltekit.head%
	</head>
	<body data-sveltekit-preload-data="hover">
		<div style="display: contents">%sveltekit.body%</div>
	</body>
</html>

Como esse script é executado de forma síncrona antes de a página pintar qualquer coisa, os usuários verão o tema correto imediatamente, sem nenhum flash.

Há uma ressalva: se um usuário tiver o JavaScript desabilitado, o script inline não será executado e o tema assumirá o padrão claro. Para suportar esse caso extremo, podemos ler o tema a partir de um cookie no servidor e injetá-lo no HTML renderizado:

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	const theme = event.cookies.get('theme-preference')

	if (!theme || !['light', 'dark'].includes(theme)) {
		return resolve(event)
	}

	return resolve(event, {
		transformPageChunk: ({ html }) => {
			return html.replace('data-theme=""', `data-theme="${theme}"`)
		}
	})
}

Agora até mesmo usuários sem JavaScript verão o tema preferido deles na primeira renderização.

[prose-37]

Criando Controles de Tema

Construindo Controles de Tema

Botão de Alternância Simples

<!-- src/lib/theme/ThemeToggle.svelte -->
<script lang="ts">
	import { getThemeContext } from './theme-context.svelte.js'

	const theme = getThemeContext()

	let label = $derived(theme.isDark ? 'Switch to light mode' : 'Switch to dark mode')
</script>

<button type="button" onclick={() => theme.toggle()} class="theme-toggle" aria-label={label}>
	{#if theme.isDark}
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
			<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
		</svg>
	{:else}
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
			<circle cx="12" cy="12" r="5" />
			<line x1="12" y1="1" x2="12" y2="3" />
			<line x1="12" y1="21" x2="12" y2="23" />
			<line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
			<line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
			<line x1="1" y1="12" x2="3" y2="12" />
			<line x1="21" y1="12" x2="23" y2="12" />
			<line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
			<line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
		</svg>
	{/if}
</button>

<style>
	.theme-toggle {
		display: flex;
		align-items: center;
		justify-content: center;
		width: 44px;
		height: 44px;
		padding: 0;
		border: none;
		border-radius: 50%;
		background-color: var(--color-surface);
		color: var(--color-foreground);
		cursor: pointer;
		transition:
			background-color 0.2s,
			transform 0.2s;
	}

	.theme-toggle:hover {
		background-color: var(--color-surface-hover);
		transform: scale(1.05);
	}

	.theme-toggle:focus-visible {
		outline: 2px solid var(--color-border-focus);
		outline-offset: 2px;
	}

	.theme-toggle svg {
		width: 22px;
		height: 22px;
	}
</style>

Seletor de Três Opções

<!-- src/lib/theme/ThemeSelector.svelte -->
<script lang="ts">
	import { getThemeContext } from './theme-context.svelte.js'
	import type { ThemePreference } from './types.js'

	const theme = getThemeContext()

	const options: { value: ThemePreference; label: string; icon: string }[] = [
		{ value: 'light', label: 'Light', icon: '☀️' },
		{ value: 'dark', label: 'Dark', icon: '🌙' },
		{ value: 'system', label: 'System', icon: '💻' }
	]
</script>

<div class="theme-selector" role="radiogroup" aria-label="Theme selection">
	{#each options as option (option.value)}
		<button
			type="button"
			role="radio"
			aria-checked={theme.preference === option.value}
			class="option"
			class:selected={theme.preference === option.value}
			onclick={() => theme.setPreference(option.value)}
		>
			<span class="icon">{option.icon}</span>
			<span class="label">{option.label}</span>
		</button>
	{/each}
</div>

{#if theme.isSystem}
	<p class="system-note">
		Currently using <strong>{theme.mode}</strong> based on system settings.
	</p>
{/if}

<style>
	.theme-selector {
		display: inline-flex;
		gap: 4px;
		padding: 4px;
		border-radius: 12px;
		background: var(--color-surface);
	}

	.option {
		display: flex;
		align-items: center;
		gap: 6px;
		padding: 8px 12px;
		border: none;
		border-radius: 8px;
		background: transparent;
		color: var(--color-foreground);
		font-size: 14px;
		cursor: pointer;
		transition: background-color 0.2s;
	}

	.option:hover:not(.selected) {
		background: var(--color-surface-hover);
	}

	.option.selected {
		background: var(--color-background);
		box-shadow: 0 1px 3px var(--color-shadow);
	}

	.icon {
		font-size: 16px;
	}

	.system-note {
		margin-top: 8px;
		font-size: 12px;
		color: var(--color-foreground-muted);
	}
</style>

Usando Temas em Componentes

Método 1: Variáveis CSS (Recomendado)

A maioria dos componentes deve simplesmente usar variáveis CSS — sem necessidade de importar contexto:

<!-- src/lib/components/Card.svelte -->
<script lang="ts">
	import type { Snippet } from 'svelte'

	interface Props {
		title: string
		children: Snippet
	}

	let { title, children }: Props = $props()
</script>

<article class="card">
	<h2>{title}</h2>
	<div class="content">{@render children()}</div>
</article>

<style>
	.card {
		background-color: var(--color-surface);
		border: 1px solid var(--color-border);
		border-radius: 12px;
		padding: 1.5rem;
		transition:
			background-color 0.3s,
			border-color 0.3s;
	}

	.card:hover {
		background-color: var(--color-surface-hover);
	}

	h2 {
		margin: 0 0 1rem;
		color: var(--color-foreground);
	}

	.content {
		color: var(--color-foreground-muted);
	}
</style>

Este componente se adapta automaticamente a qualquer tema sem importar contexto.

Método 2: Contexto para Acesso Programático

Use contexto apenas quando precisar de acesso programático (canvas, SVG, bibliotecas de terceiros):

<!-- src/lib/components/Chart.svelte -->
<script lang="ts">
	import { getThemeContext } from '$lib/theme/theme-context.svelte.js'

	const theme = getThemeContext()

	let { data }: { data: number[] } = $props()
	let canvas = $state<HTMLCanvasElement | null>(null)

	$effect(() => {
		if (!canvas) return
		const ctx = canvas.getContext('2d')
		if (!ctx) return

		// Read CSS variables for colors
		const styles = getComputedStyle(document.documentElement)
		const surface = styles.getPropertyValue('--color-surface').trim()
		const primary = styles.getPropertyValue('--color-primary').trim()

		ctx.fillStyle = surface
		ctx.fillRect(0, 0, canvas.width, canvas.height)

		ctx.strokeStyle = primary
		ctx.lineWidth = 2
		ctx.beginPath()
		data.forEach((point, i) => {
			const x = (i / data.length) * canvas.width
			const y = canvas.height - (point / 100) * canvas.height
			if (i === 0) ctx.moveTo(x, y)
			else ctx.lineTo(x, y)
		})
		ctx.stroke()
	})
</script>

<canvas bind:this={canvas} width="400" height="200"></canvas>

Erros Comuns

1. Definindo propriedades CSS via JavaScript

Em 95% dos casos, definir propriedades CSS via JavaScript é desnecessário e ineficiente. Você verá quando usar para esses 5% no próximo artigo.

// Don't do this - let CSS handle it
root.style.setProperty('--color-background', colors.background)
root.style.setProperty('--color-surface', colors.surface)
// ... 15 more lines

Apenas defina o atributo diretamente:

// CSS selectors handle the rest
document.documentElement.dataset.theme = mode

2. Importando contexto em cada componente

Você raramente precisa de acesso programático aos dados do tema.

<script>
	// Don't do this everywhere
	const theme = getThemeContext()
	const bg = theme.isDark ? '#0f172a' : '#ffffff'
</script>

Use variáveis CSS no lugar:

<style>
	.card {
		background: var(--color-surface);
	}
</style>

3. Duplicando cores em TypeScript

Não mantenha duas fontes de verdade.

export const darkColors = {
	background: '#0f172a'
	// ... same colors as CSS
}

O CSS deve ser sua única fonte de verdade.

:root[data-theme='dark'] {
	--color-background: #0f172a;
}

Estrutura do Projeto

src/
├── lib/
│   └── theme/
│       ├── types.ts                  # TypeScript interfaces (minimal)
│       ├── theme-context.svelte.ts   # Context management
│       ├── ThemeProvider.svelte      # Provider component
│       ├── ThemeToggle.svelte        # Toggle button
│       ├── ThemeSelector.svelte      # Three-way selector
│       └── index.ts                  # Public exports
├── routes/
│   └── +layout.svelte                # Wraps app in ThemeProvider
├── hooks.server.ts                   # Optional: Cookie-based SSR
├── app.html                          # Flash prevention script
└── app.css                           # ALL theme colors defined here

Considerações de Performance

A abordagem CSS-first é altamente eficiente:

Otimização nativa do navegador — A troca de variáveis CSS é gerenciada internamente pelo navegador, não pelo JavaScript
Sem loops JavaScript — Não iteramos sobre cores nem chamamos setProperty
Reflow único — Definir data-theme dispara um único recálculo de estilos
Amigável ao DevTools — Fácil de inspecionar e depurar no painel de Estilos

A maioria dos componentes deve usar variáveis CSS exclusivamente. Reserve getThemeContext() para componentes que genuinamente precisam de acesso programático.

Quando NÃO Usar Contexto

Contexto adiciona complexidade. Considere alternativas mais simples:

Cenário	Recomendação
Tema global apenas (sem sobreposições aninhadas)	Use o padrão de hook useTheme
Tema estático (sem preferência do usuário)	Apenas variáveis CSS, sem JavaScript
Biblioteca de componentes	Exponha temas através de variáveis CSS, não de contexto
Micro-frontends	Use shadow DOM ou contenção CSS

Use Contexto quando precisar especificamente de sobreposições de tema aninhadas — essa é sua capacidade única.

Conclusão

Um sistema de temas para produção com Contexto é mais simples do que pode parecer quando você segue a abordagem CSS-first:

CSS é a única fonte de verdade — Todas as cores definidas em app.css usando seletores :root[data-theme]
JavaScript apenas define um atributo — document.documentElement.dataset.theme = mode
Componentes usam variáveis CSS — Sem importações de contexto necessárias para a maioria dos componentes
Contexto habilita sobreposições aninhadas — O principal motivo para usar Contexto em vez de estado em nível de módulo

O resultado é menos código, melhor performance e depuração mais fácil.

Principais Conclusões

CSS gerencia as cores — Defina temas com seletores :root[data-theme], não com objetos JavaScript.
JavaScript define um único atributo — data-theme é tudo que você precisa. Sem loops de setProperty.
A maioria dos componentes não precisa de contexto — Basta usar var(--color-surface) no CSS.
Contexto é para sobreposições aninhadas — Esse é seu valor único em relação ao estado em nível de módulo.
Evite flash com script inline — Executa antes da renderização, definindo data-theme imediatamente.
Getters mantêm a reatividade — Retorne get mode() em vez de mode no contexto.

Leitura Adicional

Documentação Oficial

Svelte Context — Guia oficial da API de context
CSS Custom Properties — Referência MDN
prefers-color-scheme — Detecção do tema do sistema