Quando as Variáveis CSS Sozinhas Não São Suficientes

No artigo anterior sobre sistemas de tema, estabelecemos que o CSS deve ser a única fonte de verdade para as cores do tema. Para 95% das aplicações, você define cores no CSS usando seletores :root[data-theme] e o JavaScript simplesmente define o atributo data-theme. O navegador cuida de todo o resto de forma nativa e eficiente.

Mas e os outros 5%? Algumas aplicações genuinamente precisam que o JavaScript defina propriedades CSS personalizadas em tempo de execução. Este artigo aborda esses cenários em profundidade com padrões prontos para produção.

Este artigo pressupõe que você leu Construindo Sistemas de Tema Prontos para Produção com Context e compreende a abordagem CSS-first. Os padrões aqui estendem essa base para casos de uso especializados.

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

A abordagem CSS-first falha quando as cores não são conhecidas no momento da compilação. Para entender verdadeiramente por que o JavaScript se torna necessário, precisamos examinar a natureza fundamental do CSS e suas limitações.

Compreendendo o Limite entre Tempo de Compilação e Tempo de Execução

Toda aplicação web tem duas fases distintas: tempo de compilação (quando o código é compilado e empacotado) e tempo de execução (quando a aplicação é executada no navegador). Essa distinção é crucial para entender quando as propriedades CSS em JavaScript se tornam necessárias.

Tempo de compilação é quando seus arquivos CSS são processados. Ferramentas como Vite, PostCSS ou Tailwind são executadas durante essa fase. Qualquer cor definida no CSS existe permanentemente na folha de estilo que é enviada aos usuários:

/* Build-time colors: These exist BEFORE users ever visit your site */
:root {
	--color-primary: #3b82f6; /* Hardcoded at build time */
	--color-primary-hover: #2563eb; /* Hardcoded at build time */
}

:root[data-theme='dark'] {
	--color-primary: #60a5fa; /* Also hardcoded at build time */
	--color-primary-hover: #93c5fd; /* Also hardcoded at build time */
}

O navegador recebe esses valores como texto estático. Quando o JavaScript alterna data-theme, ele está simplesmente alternando entre valores pré-definidos que já existem na folha de estilo. As próprias cores nunca mudam — apenas qual conjunto está ativo.

Tempo de execução é quando a aplicação roda no navegador do usuário. É quando:

Usuários interagem com formulários e seletores de cor
Chamadas de API retornam dados de servidores
O JavaScript realiza cálculos
A aplicação lê do localStorage ou de cookies

A percepção crucial é que o CSS não pode executar lógica em tempo de execução. O CSS é declarativo — ele descreve o que deve acontecer dadas certas condições, mas não pode buscar dados, realizar cálculos ou responder a entradas arbitrárias do usuário.

Com essa base, vamos examinar cinco cenários onde as cores genuinamente não podem ser conhecidas no tempo de compilação, tornando as propriedades CSS em JavaScript necessárias.

Caso 1: Cores Personalizáveis pelo Usuário — O Problema do Infinito

O Cenário: Sua aplicação inclui um seletor de cor que permite aos usuários escolher sua própria cor de destaque. Eles clicam, selecionam #e11d48 e esperam que toda a interface reflita sua escolha.

Por que Isso Fundamentalmente Não Pode Funcionar em CSS Puro:

Os seletores de atributo do CSS só podem corresponder a valores que você define explicitamente. Para suportar cores arbitrárias do usuário, você precisaria antecipar cada valor possível:

/* The mathematical impossibility */
:root[data-user-color='#000000'] {
	--color-primary: #000000;
}
:root[data-user-color='#000001'] {
	--color-primary: #000001;
}
:root[data-user-color='#000002'] {
	--color-primary: #000002;
}
/* ... 16,777,213 more rules ... */
:root[data-user-color='#ffffff'] {
	--color-primary: #ffffff;
}

Isso geraria um arquivo CSS de aproximadamente 1,3 gigabytes. Mesmo que você limitasse os usuários a uma paleta selecionada de 100 cores, você removeu a personalização que torna o recurso valioso. Os usuários esperam combinar com sua marca, sua cor favorita ou suas necessidades de acessibilidade — não escolher de uma lista predeterminada.

O Problema Mais Profundo — Cores Derivadas:

Uma única cor do usuário normalmente precisa de vários valores derivados:

User picks: #e11d48 (rose-600)

You need:
  --color-primary:        #e11d48  (the base)
  --color-primary-hover:  #be123c  (10% darker for hover)
  --color-primary-active: #9f1239  (20% darker for active)
  --color-primary-light:  #fda4af  (for backgrounds)
  --color-primary-fg:     #ffffff  (text color with good contrast)

O CSS não pode calcular isso. Você não pode escrever:

/* This is not valid CSS */
:root {
	--color-primary-hover: darken(var(--color-primary), 10%);
}

Embora o CSS tenha color-mix() em navegadores modernos, ele ainda exige que a cor base exista primeiro — ele não pode ler de um campo de entrada.

Aplicações do Mundo Real:

Tipo de Aplicação	Por que os Usuários Precisam de Cores Personalizadas
Painéis pessoais	Combinar o espaço de trabalho com preferências, reduzir fadiga visual
Apps de anotações	Codificar cadernos, pastas e tags com cores para organização
Perfis sociais	Expressar personalidade, combinar com a marca pessoal
Ferramentas de acessibilidade	Combinações personalizadas de alto contraste para necessidades visuais
Ferramentas de design	Visualizar trabalho em diferentes contextos de cor
Plataformas de jogos	Cores de time, cores de clã, toque pessoal

A Solução com JavaScript:

O JavaScript faz a ponte entre a entrada do usuário e o CSS:

// 1. User interacts with color picker (runtime event)
const userColor = '#e11d48'

// 2. JavaScript computes derived colors (runtime calculation)
const palette = {
	base: userColor,
	hover: darken(userColor, 10), // Your utility function
	light: lighten(userColor, 40),
	foreground: getContrastColor(userColor)
}

// 3. JavaScript injects into CSS (runtime mutation)
document.documentElement.style.setProperty('--color-primary', palette.base)
document.documentElement.style.setProperty('--color-primary-hover', palette.hover)
document.documentElement.style.setProperty('--color-primary-light', palette.light)
document.documentElement.style.setProperty('--color-primary-foreground', palette.foreground)

// 4. CSS uses the values normally
// .button { background: var(--color-primary); }

O seletor de cor gera um valor. O JavaScript o transforma em uma paleta. O CSS o consome. Cada camada faz o que foi projetada para fazer.

Caso 2: Temas Orientados por API — O Problema dos Dados Externos

O Cenário: As cores da marca da sua aplicação são armazenadas em um banco de dados, gerenciadas por um CMS ou obtidas de uma API de gerenciamento de marca. Um gerente de marketing atualiza a cor primária de #3b82f6 para #6366f1, e todos os usuários veem a mudança sem nenhum deploy de código.

Por que Isso Fundamentalmente Não Pode Funcionar em CSS Puro:

Os arquivos CSS são ativos estáticos. Eles são escritos por desenvolvedores, processados por ferramentas de build e implantados em CDNs. Eles não podem:

Fazer requisições HTTP para buscar dados
Ler de bancos de dados
Analisar respostas JSON
Atualizar-se com base em estado externo

/* This is not valid CSS — CSS cannot fetch data */
:root {
	--color-primary: fetch('/api/brand/colors') .primary;
}

As cores não existem no seu código-fonte. Elas existem em um banco de dados em algum outro lugar. Seu arquivo CSS é enviado com valores de placeholder ou padrões, mas as cores "reais" vivem externamente.

O Problema Organizacional:

Considere uma estrutura de empresa típica:

┌─────────────────────────────────────────────────────────┐
│                    Brand Management                     │
├─────────────────────────────────────────────────────────┤
│  Marketing Team                                         │
│  ├── Updates brand colors seasonally                    │
│  ├── Runs A/B tests on color schemes                    │
│  ├── Manages sub-brand variations                       │
│  └── Has NO access to codebase                          │
│                                                         │
│  Design System Team                                     │
│  ├── Maintains color tokens in Figma                    │
│  ├── Syncs tokens to brand management API               │
│  └── Wants changes reflected immediately                │
│                                                         │
│  Development Team                                       │
│  ├── Should NOT be bottleneck for color changes         │
│  ├── Cannot deploy for every brand update               │
│  └── Needs decoupled, API-driven approach               │
└─────────────────────────────────────────────────────────┘

Se as cores estiverem codificadas no CSS, cada alteração exige:

O desenvolvedor atualiza o arquivo CSS
Revisão de código e aprovação
Pipeline de CI/CD é executado
Deploy para produção
Invalidação do cache do CDN

Esse processo leva horas ou dias. Com temas orientados por API, o gerente de marketing clica em "Salvar" no CMS, e os usuários veem a nova cor em minutos.

Cenários do Mundo Real:

Cenário	Fonte de Dados	Por que Não Pode Ser Estático
Sites de marketing gerenciados por CMS	Contentful, Sanity, Strapi	Editores de conteúdo controlam a identidade visual
Aplicações multi-marca	Banco de dados de marcas	Um código-fonte, muitas marcas (família Coca-Cola)
Portais de parceiros	API de parceiros	Cada revendedor tem identidade visual personalizada
Testes A/B	Serviço de experimentos	Usuários diferentes veem cores diferentes
Temas sazonais	Banco de dados de campanhas	Temas de feriados sem deploy
Personalização empresarial	Configurações do cliente	Cada cliente empresarial tem cores de marca

O Fluxo de Dados:

A Solução com JavaScript:

// The colors exist in a database, not your code
interface BrandColors {
	primary: string
	secondary: string
	accent: string
}

async function loadBrandColors(): Promise<void> {
	// 1. Fetch from external source (runtime network request)
	const response = await fetch('/api/brand/colors')
	const colors: BrandColors = await response.json()
	// Returns: { primary: '#6366f1', secondary: '#8b5cf6', accent: '#ec4899' }

	// 2. Inject into CSS (runtime mutation)
	const root = document.documentElement
	root.style.setProperty('--color-primary', colors.primary)
	root.style.setProperty('--color-secondary', colors.secondary)
	root.style.setProperty('--color-accent', colors.accent)

	// 3. CSS uses values that didn't exist until this moment
}

Estratégia de Cache:

Como as chamadas de API introduzem latência, uma solução robusta usa cache:

async function loadBrandColorsWithCache(): Promise<void> {
	// 1. Apply cached version IMMEDIATELY (no flash)
	const cached = localStorage.getItem('brand-colors')
	if (cached) {
		applyColors(JSON.parse(cached))
	}

	// 2. Fetch fresh data in background
	const fresh = await fetchBrandColors()

	// 3. Update if different
	if (JSON.stringify(fresh) !== cached) {
		applyColors(fresh)
		localStorage.setItem('brand-colors', JSON.stringify(fresh))
	}
}

Esse padrão garante que os usuários nunca vejam um flash de cores padrão em visitas repetidas, ao mesmo tempo em que recebem atualizações quando as cores da marca mudam.

Caso 3: Computação de Cores em Tempo de Execução — O Problema da Matemática

O Cenário: A partir de uma única cor base, você precisa gerar matematicamente uma paleta inteira: matizes, tons, cores complementares e cores de texto acessíveis. Isso é comum em sistemas de design, geradores de tema e visualização de dados.

Por que Isso Fundamentalmente Não Pode Funcionar em CSS Puro:

O CSS não é uma linguagem de programação. Ele não pode:

Converter espaços de cor — Transformar hex em HSL em LAB requer funções matemáticas que o CSS não possui
Realizar cálculos iterativos — Gerar 11 tons (50-950) requer loops
Calcular razões de contraste — A conformidade com WCAG requer cálculos de luminância
Aplicar teoria das cores — Esquemas complementares, análogos e triádicos precisam de rotação de matiz

O CSS moderno tem color-mix(), mas é limitado:

/* CSS color-mix can blend two colors */
.element {
	background: color-mix(in srgb, #3b82f6 70%, white);
}

/* But it CANNOT: */
/* - Generate a full Tailwind-style scale */
/* - Calculate if text should be white or black */
/* - Create complementary colors */
/* - Ensure WCAG compliance */

A Complexidade Matemática:

Considere o que gerar uma escala de cores no estilo Tailwind requer:

Input: #6366f1 (indigo-500)

Step 1: Convert to LAB color space (perceptually uniform)
  L: 52.93, a: 46.78, b: -77.31

Step 2: Interpolate toward white for lighter shades
  50:  L: 97.2, a: 2.1, b: -3.5   → #eef2ff
  100: L: 94.3, a: 4.8, b: -8.2   → #e0e7ff
  200: L: 88.1, a: 10.2, b: -18.4 → #c7d2fe
  ... (continue for 300, 400)

Step 3: Interpolate toward black for darker shades
  600: L: 43.8, a: 52.1, b: -82.3 → #4f46e5
  700: L: 35.2, a: 54.8, b: -78.9 → #4338ca
  ... (continue for 800, 900, 950)

Step 4: Convert each LAB value back to hex

Step 5: Calculate foreground color
  Luminance of #6366f1: 0.21
  Contrast with white: 4.56:1 ✓ (passes WCAG AA)
  Contrast with black: 4.58:1 ✓
  → Use white (slightly better contrast)

São aproximadamente 50 operações matemáticas por escala de cores. O CSS não pode realizar nenhuma delas.

Por que o Espaço de Cor LAB É Importante:

A percepção humana de cor é não linear. RGB e HSL criam escalas visualmente desiguais:

RGB interpolation (looks wrong):
#ffffff → #6366f1 → #000000
  50:  Very washed out
  200: Still too light
  400: Sudden jump in saturation
  700: Muddy and dark
  950: Pure black too early

LAB interpolation (looks right):
#ffffff → #6366f1 → #000000
  50:  Barely tinted white
  200: Soft, balanced tint
  400: Clearly colored but light
  700: Rich, deep color
  950: Very dark but still colored

Bibliotecas como Chroma.js lidam com essa complexidade:

import chroma from 'chroma-js'

// Generate perceptually uniform scale
const scale = chroma
	.scale(['#ffffff', '#6366f1', '#000000'])
	.mode('lab') // Use LAB color space
	.colors(11) // Generate 11 colors

// Calculate accessible text color
const bg = chroma('#6366f1')
const whiteContrast = chroma.contrast(bg, 'white') // 4.56
const blackContrast = chroma.contrast(bg, 'black') // 4.58
const textColor = whiteContrast > blackContrast ? 'white' : 'black'

// Generate complementary color (180° hue rotation)
const complement = chroma('#6366f1').set('hsl.h', '+180') // #f1ef63

Aplicações do Mundo Real:

Aplicação	Matemática de Cor Necessária
Geradores de sistema de design	Paleta completa a partir da cor da marca
Visualização de dados	Escalas de gradiente para mapas de calor, mapas coropléticos
Verificadores de acessibilidade	Cálculos de razão de contraste WCAG
Construtores de tema	Usuário escolhe uma cor, o app gera um esquema coeso
Indicadores de progresso	Transições de cor baseadas em porcentagem (vermelho → amarelo → verde)
UIs de análise de sentimento	Mapeamento de cor para pontuações positivas/negativas

A Solução com JavaScript:

import chroma from 'chroma-js'

function generateAndApplyPalette(baseColor: string): void {
	const base = chroma(baseColor)

	// Generate scale using perceptually uniform color space
	const lightScale = chroma.scale(['#ffffff', base]).mode('lab').colors(6)
	const darkScale = chroma.scale([base, '#000000']).mode('lab').colors(6)

	// Calculate accessible foreground
	const foreground = chroma.contrast(base, 'white') >= 4.5 ? '#ffffff' : '#0f172a'

	// Apply all computed values to CSS
	const root = document.documentElement
	root.style.setProperty('--color-primary-50', lightScale[1])
	root.style.setProperty('--color-primary-100', lightScale[2])
	root.style.setProperty('--color-primary-200', lightScale[3])
	root.style.setProperty('--color-primary-300', lightScale[4])
	root.style.setProperty('--color-primary-400', lightScale[5])
	root.style.setProperty('--color-primary-500', base.hex())
	root.style.setProperty('--color-primary-600', darkScale[1])
	root.style.setProperty('--color-primary-700', darkScale[2])
	root.style.setProperty('--color-primary-800', darkScale[3])
	root.style.setProperty('--color-primary-900', darkScale[4])
	root.style.setProperty('--color-primary-950', darkScale[5])
	root.style.setProperty('--color-primary-foreground', foreground)
}

Caso 4: Integração com Bibliotecas de Terceiros — O Problema do Mundo Apenas em JavaScript

O Cenário: Você está usando Chart.js, D3.js, Three.js ou qualquer biblioteca baseada em Canvas. Essas bibliotecas precisam de valores de cor como strings JavaScript. Elas não podem ler variáveis CSS diretamente.

Por que Isso Fundamentalmente Não Pode Funcionar Apenas com Variáveis CSS:

As bibliotecas de terceiros operam em JavaScript, não em CSS. Quando você configura o Chart.js:

new Chart(canvas, {
	data: {
		datasets: [
			{
				borderColor: '#3b82f6' // ✅ This works
			}
		]
	}
})

A biblioteca pega essa string e a passa diretamente para a API Canvas 2D:

// Inside Chart.js (simplified)
ctx.strokeStyle = config.borderColor // Sets canvas stroke color
ctx.stroke() // Draws the line

A API Canvas espera uma string de cor como '#3b82f6' ou 'rgb(59, 130, 246)'. Ela não entende sintaxe CSS:

ctx.strokeStyle = 'var(--color-primary)' // ❌ Draws nothing (invalid color)

A API Canvas foi projetada antes de as propriedades customizadas do CSS existirem. Ela não tem mecanismo para resolvê-las.

O Mesmo Problema Existe em Muitas Bibliotecas:

Biblioteca	Por que variáveis CSS não funcionam
Chart.js	Passa cores diretamente para o contexto Canvas 2D
D3.js	Define atributos SVG como strings, não CSS
Three.js	WebGL requer valores de cor numéricos (0x3b82f6)
Mapbox/Leaflet	Estilização GeoJSON usa objetos JavaScript
GSAP/Anime.js	Interpola entre valores de cor em JS
jsPDF	A especificação PDF requer cores explícitas
Fabric.js	Biblioteca de manipulação de Canvas
PixiJS	Renderização baseada em WebGL

O Padrão de Ponte:

Você precisa ler os valores CSS computados e passá-los para as bibliotecas JavaScript:

// 1. Read what CSS has computed
function getThemeColors(): Record<string, string> {
	const styles = getComputedStyle(document.documentElement)
	return {
		primary: styles.getPropertyValue('--color-primary').trim(),
		secondary: styles.getPropertyValue('--color-secondary').trim(),
		surface: styles.getPropertyValue('--color-surface').trim(),
		foreground: styles.getPropertyValue('--color-foreground').trim(),
		border: styles.getPropertyValue('--color-border').trim()
	}
}

// 2. Pass resolved values to library
const colors = getThemeColors()

new Chart(canvas, {
	data: {
		datasets: [
			{
				borderColor: colors.primary, // ✅ Resolved hex value
				backgroundColor: colors.surface // ✅ Resolved hex value
			}
		]
	},
	options: {
		scales: {
			x: {
				grid: { color: colors.border } // ✅ Resolved hex value
			}
		}
	}
})

O Problema de Mudança de Tema:

Quando seu tema muda (claro → escuro), as variáveis CSS se atualizam automaticamente. Mas as bibliotecas que já receberam os valores antigos não sabem sobre a mudança:

Initial state:
  CSS: --color-primary: #3b82f6 (light theme blue)
  Chart.js has: borderColor: '#3b82f6'

User switches to dark theme:
  CSS: --color-primary: #60a5fa (dark theme blue)
  Chart.js still has: borderColor: '#3b82f6' ← STALE!

Você deve detectar mudanças de tema e recriar ou atualizar a instância da biblioteca:

$effect(() => {
	// Access theme.mode to create reactive dependency
	const currentMode = theme.mode

	// Read fresh colors after theme change
	const colors = getThemeColors()

	// Destroy old chart
	if (chart) {
		chart.destroy()
	}

	// Create new chart with updated colors
	chart = new Chart(canvas, {
		// ... config using new colors
	})

	// Cleanup on effect re-run or component unmount
	return () => {
		if (chart) chart.destroy()
	}
})

Por que Este Padrão é Necessário:

Caso 5: Tematização Multi-Tenant White-Label SaaS — O Problema da Identidade Desconhecida

O Cenário: Você está construindo um produto SaaS onde cada cliente (tenant) tem sua própria identidade visual. Quando alguém visita acme.yourapp.com, vê o azul da Acme. Quando alguém visita globex.yourapp.com, vê o verde da Globex. Mesmo código-base, aparências diferentes.

Por que Isso Fundamentalmente Não Pode Funcionar em CSS Puro:

Você não sabe qual tenant está visitando até o tempo de execução. A identidade do tenant vem de:

Subdomínio: acme.yourapp.com → Tenant: "acme"
Caminho: yourapp.com/org/acme → Tenant: "acme"
Autenticação: Usuário faz login → Pertence à organização "acme"
Cookie/Header: X-Tenant-ID: acme

O CSS não consegue ler nenhum desses. O CSS não sabe qual URL o usuário digitou ou quem ele autenticou.

O Problema de Escala:

Você poderia teoricamente pré-gerar CSS para cada tenant:

:root[data-tenant='acme'] {
	--color-primary: #3b82f6;
	--color-header-bg: #1e3a5f;
}

:root[data-tenant='globex'] {
	--color-primary: #22c55e;
	--color-header-bg: #14532d;
}

:root[data-tenant='initech'] {
	--color-primary: #8b5cf6;
	--color-header-bg: #4c1d95;
}

/* ... 997 more tenants ... */

Esta abordagem tem problemas catastróficos:

Problema	Impacto
Tamanho do bundle CSS	Cresce linearmente com os tenants. 1000 tenants = arquivo enorme
Acoplamento de deploy	Novo tenant ou mudança de cor = deploy de código
Self-service impossível	Tenants não podem personalizar sua própria identidade visual
Tempo de build	Desacelera conforme o número de tenants cresce
Invalidação de cache	Qualquer mudança de tenant invalida o cache de todos

A Realidade do Negócio:

Produtos SaaS frequentemente têm estes requisitos:

Self-service do tenant: Admins personalizam a identidade visual sem contatar o suporte
Atualizações instantâneas: Mudanças visíveis imediatamente, não após o deploy
Escala ilimitada: Suporte a milhares de tenants sem alterações de código
Isolamento completo: A identidade visual de um tenant nunca vaza para outro
Além das cores: Logos customizados, favicons, fontes e títulos de página

Aplicações do Mundo Real:

Tipo de Produto	Por que Tematização Multi-Tenant	Exemplos
B2B SaaS	Cada empresa vê sua marca	Slack, Notion, Linear
Plataformas de e-commerce	Cada lojista tem loja com sua marca	Shopify, BigCommerce
Plataformas LMS	Escolas veem identidade institucional	Canvas, Moodle
Portais de saúde	Clínicas têm portais de pacientes com marca	Epic MyChart
Ferramentas para agências	White-label para clientes de agências	Muitas ferramentas de marketing
Software para franquias	Cada unidade tem identidade local	Sistemas POS

A Arquitetura:

O Caminho Crítico do SSR:

Sem tratamento no lado do servidor, os usuários veem um flash das cores padrão:

Without SSR:
  1. Browser requests page
  2. Server sends HTML with DEFAULT colors in CSS
  3. Page renders with DEFAULT colors
  4. JavaScript loads
  5. JavaScript detects tenant
  6. JavaScript fetches branding
  7. JavaScript applies colors
  8. Page FLASHES to tenant colors  ← BAD UX

With SSR:
  1. Browser requests page
  2. Server detects tenant from subdomain
  3. Server fetches branding (cached in Redis)
  4. Server injects tenant colors in <style> tag
  5. Page renders with CORRECT colors immediately  ← GOOD UX
  6. JavaScript hydrates and takes over

A Solução JavaScript (Completa):

// src/hooks.server.ts — Server-side tenant detection
import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	// 1. Extract tenant from subdomain
	const host = event.request.headers.get('host') ?? ''
	const subdomain = host.split('.')[0]

	// 2. Skip non-tenant subdomains
	if (['www', 'app', 'api'].includes(subdomain)) {
		return resolve(event)
	}

	// 3. Fetch tenant branding (with caching)
	const branding = await getTenantBranding(subdomain)

	if (!branding) {
		return resolve(event) // Unknown tenant, use defaults
	}

	// 4. Inject branding into HTML
	return resolve(event, {
		transformPageChunk: ({ html }) => {
			const styles = `
        <style id="tenant-theme">
          :root {
            --color-primary: ${branding.primary};
            --color-primary-hover: ${branding.primaryHover};
            --color-header-bg: ${branding.headerBg};
            --color-header-fg: ${branding.headerFg};
          }
        </style>
      `
			return html.replace('</head>', `${styles}</head>`)
		}
	})
}

// Caching layer
const brandingCache = new Map<string, TenantBranding>()

async function getTenantBranding(slug: string): Promise<TenantBranding | null> {
	// Check memory cache first
	if (brandingCache.has(slug)) {
		return brandingCache.get(slug)!
	}

	// Fetch from database
	const branding = await db.tenants.findUnique({
		where: { slug },
		select: { branding: true }
	})

	if (branding) {
		brandingCache.set(slug, branding) // Cache for future requests
	}

	return branding
}

Resumo: O Framework de Decisão

Use este fluxograma para decidir se você precisa de propriedades CSS via JavaScript:

Pergunta	Se Sim →	Se Não →
Todas as cores estão definidas nos seus arquivos CSS?	CSS-first	Precisa JavaScript
O marketing pode mudar cores sem deploy?	Precisa JavaScript	CSS-first está ok
Os usuários escolhem suas próprias cores?	Precisa JavaScript	CSS-first está ok
Você gera paletas a partir de uma cor base?	Precisa JavaScript	CSS-first está ok
Chart.js/D3/Canvas precisam das cores do seu tema?	Precisa JavaScript	CSS-first está ok
Cada cliente vê uma identidade visual diferente?	Precisa JavaScript	CSS-first está ok

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

Se as cores são determinadas em tempo de execução → Use JavaScript para defini-las.

A maioria dos aplicativos (aproximadamente 95%) tem paletas de cores estáticas, portanto CSS-first é a escolha padrão. Use propriedades CSS via JavaScript apenas quando você genuinamente precisar de personalização em tempo de execução.

Utilitários Principais

Antes de mergulhar em casos de uso específicos, vamos estabelecer os utilitários fundamentais que todos os padrões compartilham:

// src/lib/theme/dynamic-colors.svelte.ts
import { browser } from '$app/environment'

/**
 * Applies dynamic colors to CSS custom properties.
 * Use this ONLY for runtime-determined colors.
 */
export function applyDynamicColors(colors: Record<string, string>): void {
	if (!browser) return

	const root = document.documentElement
	for (const [key, value] of Object.entries(colors)) {
		root.style.setProperty(`--color-${key}`, value)
	}
}

/**
 * Removes dynamic colors, reverting to CSS defaults.
 * CSS will fall back to values defined in your stylesheet.
 */
export function clearDynamicColors(keys: string[]): void {
	if (!browser) return

	const root = document.documentElement
	for (const key of keys) {
		root.style.removeProperty(`--color-${key}`)
	}
}

/**
 * Reads current CSS custom property values.
 * Useful for passing colors to third-party libraries.
 */
export function getComputedColors(keys: string[]): Record<string, string> {
	if (!browser) return {}

	const styles = getComputedStyle(document.documentElement)
	const colors: Record<string, string> = {}

	for (const key of keys) {
		colors[key] = styles.getPropertyValue(`--color-${key}`).trim()
	}

	return colors
}

Esses utilitários formam a base para todos os padrões de tematização dinâmica. Observe que eles são defensivos em relação ao SSR — sempre verificando browser antes de acessar document.

Padrão 1: Seletor de Cores Personalizável pelo Usuário

A necessidade de tematização em tempo de execução mais comum é permitir que os usuários escolham sua própria cor de destaque ou marca. Isso requer gerar uma paleta completa a partir de uma única escolha de cor.

Utilitários de Matemática de Cores

Primeiro, vamos construir algumas funções puras para manipulação de cores:

// src/lib/theme/color-utils.ts

/**
 * Converts hex color to RGB components.
 */
export function hexToRgb(hex: string): { r: number; g: number; b: number } {
	const cleanHex = hex.replace('#', '')
	return {
		r: parseInt(cleanHex.slice(0, 2), 16),
		g: parseInt(cleanHex.slice(2, 4), 16),
		b: parseInt(cleanHex.slice(4, 6), 16)
	}
}

/**
 * Converts RGB components to hex color.
 */
export function rgbToHex(r: number, g: number, b: number): string {
	const toHex = (n: number) =>
		Math.max(0, Math.min(255, Math.round(n)))
			.toString(16)
			.padStart(2, '0')
	return `#${toHex(r)}${toHex(g)}${toHex(b)}`
}

/**
 * Adjusts brightness of a hex color.
 * Positive percent lightens, negative darkens.
 */
export function adjustBrightness(hex: string, percent: number): string {
	const { r, g, b } = hexToRgb(hex)
	const amount = Math.round(2.55 * percent)
	return rgbToHex(r + amount, g + amount, b + amount)
}

/**
 * Calculates relative luminance for contrast calculations.
 * Returns value between 0 (black) and 1 (white).
 */
export function getLuminance(hex: string): number {
	const { r, g, b } = hexToRgb(hex)
	return (0.299 * r + 0.587 * g + 0.114 * b) / 255
}

/**
 * Returns black or white depending on which has better contrast.
 */
export function getContrastColor(bgHex: string): string {
	return getLuminance(bgHex) > 0.5 ? '#000000' : '#ffffff'
}

/**
 * Generates a simple palette from a base color.
 */
export function generateSimplePalette(baseColor: string) {
	return {
		light: adjustBrightness(baseColor, 30),
		base: baseColor,
		dark: adjustBrightness(baseColor, -20),
		foreground: getContrastColor(baseColor)
	}
}

O Componente Seletor de Cores

Agora vamos construir um seletor de cores completo que aplica as mudanças em tempo real:

<!-- src/lib/components/ColorCustomizer.svelte -->
<script lang="ts">
	import { applyDynamicColors, clearDynamicColors } from '$lib/theme/dynamic-colors.svelte.js'
	import { generateSimplePalette, getContrastColor } from '$lib/theme/color-utils.js'
	import { browser } from '$app/environment'

	interface Props {
		/** Initial color value */
		initialColor?: string
		/** Storage key for persistence */
		storageKey?: string
		/** Callback when color changes */
		onchange?: (color: string) => void
	}

	let { initialColor = '#3b82f6', storageKey = 'user-accent-color', onchange }: Props = $props()

	// Load saved color or use initial
	function loadSavedColor(): string {
		if (!browser) return initialColor
		return localStorage.getItem(storageKey) ?? initialColor
	}

	let accentColor = $state(loadSavedColor())
	let palette = $derived(generateSimplePalette(accentColor))

	// Apply colors whenever accent changes
	$effect(() => {
		applyDynamicColors({
			primary: palette.base,
			'primary-light': palette.light,
			'primary-dark': palette.dark,
			'primary-hover': palette.light,
			'primary-active': palette.dark,
			'primary-foreground': palette.foreground
		})

		// Persist to localStorage
		if (browser) {
			localStorage.setItem(storageKey, accentColor)
		}

		// Notify parent
		onchange?.(accentColor)
	})

	function handleColorInput(event: Event) {
		const input = event.target as HTMLInputElement
		accentColor = input.value
	}

	function resetToDefault() {
		accentColor = initialColor
		if (browser) {
			localStorage.removeItem(storageKey)
		}
	}

	// Preset colors for quick selection
	const presets = [
		{ name: 'Blue', value: '#3b82f6' },
		{ name: 'Purple', value: '#8b5cf6' },
		{ name: 'Pink', value: '#ec4899' },
		{ name: 'Red', value: '#ef4444' },
		{ name: 'Orange', value: '#f97316' },
		{ name: 'Green', value: '#22c55e' },
		{ name: 'Teal', value: '#14b8a6' }
	]
</script>

<div class="color-customizer">
	<div class="picker-section">
		<label class="color-label">
			<span>Accent Color</span>
			<input type="color" value={accentColor} oninput={handleColorInput} class="color-input" />
		</label>
		<code class="color-value">{accentColor}</code>
	</div>

	<div class="presets">
		<span class="presets-label">Quick picks:</span>
		{#each presets as preset (preset.value)}
			<button
				type="button"
				class="preset-btn"
				class:active={accentColor === preset.value}
				style:background-color={preset.value}
				style:color={getContrastColor(preset.value)}
				onclick={() => (accentColor = preset.value)}
				title={preset.name}
			>
				{#if accentColor === preset.value}✓{/if}
			</button>
		{/each}
	</div>

	<div class="palette-preview">
		<div class="swatch" style:background-color={palette.light}>Light</div>
		<div class="swatch" style:background-color={palette.base}>Base</div>
		<div class="swatch" style:background-color={palette.dark}>Dark</div>
	</div>

	<div class="preview-buttons">
		<button class="btn-primary">Primary Button</button>
		<button class="btn-primary-outline">Outline Button</button>
		<button type="button" class="btn-reset" onclick={resetToDefault}> Reset to Default </button>
	</div>
</div>

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

	.picker-section {
		display: flex;
		align-items: center;
		gap: 1rem;
		margin-bottom: 1rem;
	}

	.color-label {
		display: flex;
		align-items: center;
		gap: 0.75rem;
		font-weight: 500;
	}

	.color-input {
		width: 48px;
		height: 48px;
		padding: 0;
		border: 2px solid var(--color-border);
		border-radius: 8px;
		cursor: pointer;
	}

	.color-input::-webkit-color-swatch-wrapper {
		padding: 2px;
	}

	.color-input::-webkit-color-swatch {
		border-radius: 4px;
		border: none;
	}

	.color-value {
		font-family: monospace;
		font-size: 0.875rem;
		color: var(--color-foreground-muted);
	}

	.presets {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		margin-bottom: 1.5rem;
	}

	.presets-label {
		font-size: 0.875rem;
		color: var(--color-foreground-muted);
	}

	.preset-btn {
		width: 32px;
		height: 32px;
		border: 2px solid transparent;
		border-radius: 6px;
		cursor: pointer;
		font-size: 0.875rem;
		transition:
			transform 0.15s,
			border-color 0.15s;
	}

	.preset-btn:hover {
		transform: scale(1.1);
	}

	.preset-btn.active {
		border-color: var(--color-foreground);
	}

	.palette-preview {
		display: flex;
		gap: 4px;
		margin-bottom: 1.5rem;
	}

	.swatch {
		flex: 1;
		padding: 1rem;
		text-align: center;
		font-size: 0.75rem;
		font-weight: 500;
		color: white;
		text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
		border-radius: 6px;
	}

	.preview-buttons {
		display: flex;
		gap: 0.75rem;
		flex-wrap: wrap;
	}

	.btn-primary {
		padding: 0.625rem 1.25rem;
		background-color: var(--color-primary);
		color: var(--color-primary-foreground);
		border: none;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
		transition: background-color 0.2s;
	}

	.btn-primary:hover {
		background-color: var(--color-primary-hover);
	}

	.btn-primary:active {
		background-color: var(--color-primary-active);
	}

	.btn-primary-outline {
		padding: 0.625rem 1.25rem;
		background: transparent;
		color: var(--color-primary);
		border: 2px solid var(--color-primary);
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
		transition:
			background-color 0.2s,
			color 0.2s;
	}

	.btn-primary-outline:hover {
		background-color: var(--color-primary);
		color: var(--color-primary-foreground);
	}

	.btn-reset {
		padding: 0.625rem 1.25rem;
		background: var(--color-surface-hover);
		color: var(--color-foreground-muted);
		border: none;
		border-radius: 6px;
		font-size: 0.875rem;
		cursor: pointer;
	}
</style>

Usando o Personalizador de Cores

<!-- src/routes/settings/+page.svelte -->
<script>
	import ColorCustomizer from '$lib/components/ColorCustomizer.svelte'

	function handleColorChange(color: string) {
		// Optionally sync to server
		fetch('/api/user/preferences', {
			method: 'PATCH',
			body: JSON.stringify({ accentColor: color })
		})
	}
</script>

<h1>Appearance Settings</h1>

<section>
	<h2>Customize Your Theme</h2>
	<p>Choose an accent color that matches your style.</p>

	<ColorCustomizer
		initialColor="#3b82f6"
		storageKey="user-accent-color"
		onchange={handleColorChange}
	/>
</section>

Padrão 2: Temas Orientados por API

Quando as cores da marca vêm de uma API de backend, CMS ou banco de dados, você precisa buscá-las e aplicá-las em tempo de execução. Este padrão é comum para:

Aplicações multi-marca
Sites de marketing gerenciados por CMS
Personalização de portal de parceiros
Identidade visual específica da organização

// src/lib/theme/brand-theme.svelte.ts
import { browser } from '$app/environment'
import { applyDynamicColors, clearDynamicColors } from './dynamic-colors.svelte.js'

export interface BrandColors {
	primary: string
	primaryHover: string
	secondary: string
	accent: string
	headerBg?: string
	headerFg?: string
}

export interface BrandTheme {
	id: string
	name: string
	colors: BrandColors
	logo?: string
}

// Module-level reactive state
let currentBrand = $state<BrandTheme | null>(null)
let isLoading = $state(false)
let error = $state<string | null>(null)

const BRAND_COLOR_KEYS = [
	'primary',
	'primary-hover',
	'secondary',
	'accent',
	'header-bg',
	'header-fg'
]

/**
 * Fetches brand theme from API and applies it.
 */
export async function loadBrandTheme(brandId: string): Promise<BrandTheme | null> {
	if (!browser) return null

	isLoading = true
	error = null

	try {
		const response = await fetch(`/api/brands/${brandId}/theme`)

		if (!response.ok) {
			throw new Error(`Failed to load brand theme: ${response.status}`)
		}

		const theme: BrandTheme = await response.json()
		applyBrandTheme(theme)

		// Cache for faster subsequent loads
		cacheBrandTheme(brandId, theme)

		return theme
	} catch (e) {
		error = e instanceof Error ? e.message : 'Failed to load brand theme'
		console.error('Brand theme error:', e)
		return null
	} finally {
		isLoading = false
	}
}

/**
 * Applies a brand theme to CSS custom properties.
 */
export function applyBrandTheme(theme: BrandTheme): void {
	currentBrand = theme

	const colors: Record<string, string> = {
		primary: theme.colors.primary,
		'primary-hover': theme.colors.primaryHover,
		secondary: theme.colors.secondary,
		accent: theme.colors.accent
	}

	// Optional header colors
	if (theme.colors.headerBg) {
		colors['header-bg'] = theme.colors.headerBg
	}
	if (theme.colors.headerFg) {
		colors['header-fg'] = theme.colors.headerFg
	}

	applyDynamicColors(colors)
}

/**
 * Loads cached theme immediately, then refreshes from API.
 * Prevents flash of default colors on repeat visits.
 */
export function loadBrandThemeWithCache(brandId: string): void {
	if (!browser) return

	// Apply cached version immediately
	const cached = getCachedBrandTheme(brandId)
	if (cached) {
		applyBrandTheme(cached)
	}

	// Refresh from API in background
	loadBrandTheme(brandId)
}

/**
 * Clears brand theme, reverting to CSS defaults.
 */
export function clearBrandTheme(): void {
	currentBrand = null
	clearDynamicColors(BRAND_COLOR_KEYS)
}

/**
 * Access current brand state reactively.
 */
export function useBrandTheme() {
	return {
		get brand() {
			return currentBrand
		},
		get isLoading() {
			return isLoading
		},
		get error() {
			return error
		},
		get hasBrand() {
			return currentBrand !== null
		},
		load: loadBrandTheme,
		loadWithCache: loadBrandThemeWithCache,
		apply: applyBrandTheme,
		clear: clearBrandTheme
	}
}

// Cache helpers
function cacheBrandTheme(brandId: string, theme: BrandTheme): void {
	try {
		localStorage.setItem(`brand-theme-${brandId}`, JSON.stringify(theme))
	} catch {
		// localStorage might be full or disabled
	}
}

function getCachedBrandTheme(brandId: string): BrandTheme | null {
	try {
		const cached = localStorage.getItem(`brand-theme-${brandId}`)
		return cached ? JSON.parse(cached) : null
	} catch {
		return null
	}
}

Usando Temas Orientados por API

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { onMount } from 'svelte'
	import { useBrandTheme } from '$lib/theme/brand-theme.svelte.js'
	import ThemeProvider from '$lib/theme/ThemeProvider.svelte'

	let { children, data } = $props()

	const brandTheme = useBrandTheme()

	onMount(() => {
		// Load brand from route data or user's organization
		if (data.brandId) {
			brandTheme.loadWithCache(data.brandId)
		}
	})
</script>

<ThemeProvider>
	{#if brandTheme.isLoading && !brandTheme.brand}
		<div class="loading-brand">Loading brand theme...</div>
	{/if}

	{#if brandTheme.error}
		<div class="brand-error">
			<p>Failed to load brand theme. Using defaults.</p>
		</div>
	{/if}

	<header class="app-header">
		{#if brandTheme.brand?.logo}
			<img src={brandTheme.brand.logo} alt="{brandTheme.brand.name} logo" />
		{/if}
		<span>{brandTheme.brand?.name ?? 'Your App'}</span>
	</header>

	{@render children()}
</ThemeProvider>

<style>
	.app-header {
		display: flex;
		align-items: center;
		gap: 1rem;
		padding: 1rem;
		background-color: var(--color-header-bg, var(--color-primary));
		color: var(--color-header-fg, var(--color-primary-foreground));
	}

	.app-header img {
		height: 32px;
		width: auto;
	}
</style>

Padrão 3: Computação de Cores em Tempo de Execução com Chroma.js

Quando você precisa de manipulação de cores sofisticada — gerando paletas completas, garantindo acessibilidade ou criando esquemas de cores harmoniosos — a matemática de cores em JavaScript puro não é suficiente. O Chroma.js oferece ciência de cores de nível profissional.

Configuração

npm install chroma-js
npm install -D @types/chroma-js

Gerador de Paleta

// src/lib/theme/color-palette.svelte.ts
import { browser } from '$app/environment'
import chroma from 'chroma-js'
import { applyDynamicColors } from './dynamic-colors.svelte.js'

export interface ColorScale {
	50: string
	100: string
	200: string
	300: string
	400: string
	500: string // base color
	600: string
	700: string
	800: string
	900: string
	950: string
}

/**
 * Generates a Tailwind-style color scale from a single base color.
 * Uses perceptually uniform LAB color space for smooth transitions.
 */
export function generateColorScale(baseColor: string): ColorScale {
	const base = chroma(baseColor)

	// Generate lighter shades (50-400)
	const lightScale = chroma.scale(['#ffffff', base]).mode('lab').colors(6)

	// Generate darker shades (600-950)
	const darkScale = chroma.scale([base, '#000000']).mode('lab').colors(6)

	return {
		50: lightScale[1],
		100: lightScale[2],
		200: lightScale[3],
		300: lightScale[4],
		400: lightScale[5],
		500: base.hex(),
		600: darkScale[1],
		700: darkScale[2],
		800: darkScale[3],
		900: darkScale[4],
		950: darkScale[5]
	}
}

/**
 * Determines the best text color for a background.
 * Uses WCAG contrast ratio guidelines.
 */
export function getAccessibleForeground(bgColor: string): string {
	const bg = chroma(bgColor)
	const white = chroma('#ffffff')
	const dark = chroma('#0f172a')

	// Calculate contrast ratios
	const whiteContrast = chroma.contrast(bg, white)
	const darkContrast = chroma.contrast(bg, dark)

	// WCAG AA requires 4.5:1 for normal text
	// Prefer the color with better contrast
	return whiteContrast >= darkContrast ? '#ffffff' : '#0f172a'
}

/**
 * Applies a complete color scale as CSS custom properties.
 */
export function applyColorScale(name: string, baseColor: string): void {
	if (!browser) return

	const scale = generateColorScale(baseColor)
	const foreground = getAccessibleForeground(baseColor)

	applyDynamicColors({
		[`${name}-50`]: scale[50],
		[`${name}-100`]: scale[100],
		[`${name}-200`]: scale[200],
		[`${name}-300`]: scale[300],
		[`${name}-400`]: scale[400],
		[`${name}-500`]: scale[500],
		[`${name}-600`]: scale[600],
		[`${name}-700`]: scale[700],
		[`${name}-800`]: scale[800],
		[`${name}-900`]: scale[900],
		[`${name}-950`]: scale[950],
		// Semantic aliases
		[name]: scale[500],
		[`${name}-hover`]: scale[600],
		[`${name}-active`]: scale[700],
		[`${name}-foreground`]: foreground
	})
}

/**
 * Generates a complementary color scheme from a primary color.
 */
export function applyComplementaryScheme(primaryColor: string): void {
	if (!browser) return

	const primary = chroma(primaryColor)

	// Complementary: opposite on color wheel (180°)
	const secondary = primary.set('hsl.h', '+180')

	// Accent: 90° offset for visual interest
	const accent = primary.set('hsl.h', '+90')

	applyColorScale('primary', primary.hex())
	applyColorScale('secondary', secondary.hex())
	applyColorScale('accent', accent.hex())
}

/**
 * Generates an analogous color scheme (colors next to each other).
 */
export function applyAnalogousScheme(primaryColor: string): void {
	if (!browser) return

	const primary = chroma(primaryColor)
	const secondary = primary.set('hsl.h', '+30')
	const accent = primary.set('hsl.h', '-30')

	applyColorScale('primary', primary.hex())
	applyColorScale('secondary', secondary.hex())
	applyColorScale('accent', accent.hex())
}

/**
 * Creates a triadic color scheme (three colors equally spaced).
 */
export function applyTriadicScheme(primaryColor: string): void {
	if (!browser) return

	const primary = chroma(primaryColor)
	const secondary = primary.set('hsl.h', '+120')
	const accent = primary.set('hsl.h', '+240')

	applyColorScale('primary', primary.hex())
	applyColorScale('secondary', secondary.hex())
	applyColorScale('accent', accent.hex())
}

Componente Gerador de Paleta

<!-- src/lib/components/PaletteGenerator.svelte -->
<script lang="ts">
	import {
		generateColorScale,
		applyColorScale,
		applyComplementaryScheme,
		applyAnalogousScheme,
		applyTriadicScheme,
		getAccessibleForeground
	} from '$lib/theme/color-palette.svelte.js'

	type SchemeType = 'single' | 'complementary' | 'analogous' | 'triadic'

	let baseColor = $state('#6366f1')
	let schemeType = $state<SchemeType>('single')
	let scale = $derived(generateColorScale(baseColor))

	// Apply scheme whenever inputs change
	$effect(() => {
		switch (schemeType) {
			case 'complementary':
				applyComplementaryScheme(baseColor)
				break
			case 'analogous':
				applyAnalogousScheme(baseColor)
				break
			case 'triadic':
				applyTriadicScheme(baseColor)
				break
			default:
				applyColorScale('primary', baseColor)
		}
	})

	const schemeOptions: { value: SchemeType; label: string; description: string }[] = [
		{ value: 'single', label: 'Single Color', description: 'One color with light/dark variations' },
		{
			value: 'complementary',
			label: 'Complementary',
			description: 'Opposite colors for high contrast'
		},
		{ value: 'analogous', label: 'Analogous', description: 'Adjacent colors for harmony' },
		{ value: 'triadic', label: 'Triadic', description: 'Three evenly spaced colors' }
	]
</script>

<div class="palette-generator">
	<div class="controls">
		<label class="color-control">
			<span>Base Color</span>
			<input type="color" bind:value={baseColor} />
			<code>{baseColor}</code>
		</label>

		<fieldset class="scheme-selector">
			<legend>Color Scheme</legend>
			{#each schemeOptions as option (option.value)}
				<label class="scheme-option">
					<input type="radio" name="scheme" value={option.value} bind:group={schemeType} />
					<span class="option-content">
						<strong>{option.label}</strong>
						<small>{option.description}</small>
					</span>
				</label>
			{/each}
		</fieldset>
	</div>

	<div class="scale-preview">
		<h3>Generated Scale</h3>
		<div class="scale-row">
			{#each Object.entries(scale) as [shade, color] (shade)}
				{@const fg = getAccessibleForeground(color)}
				<div class="scale-swatch" style:background-color={color} style:color={fg}>
					<span class="shade-label">{shade}</span>
					<span class="color-hex">{color}</span>
				</div>
			{/each}
		</div>
	</div>

	<div class="usage-preview">
		<h3>Live Preview</h3>
		<div class="preview-cards">
			<div class="preview-card primary">
				<h4>Primary</h4>
				<button class="preview-btn">Button</button>
			</div>
			{#if schemeType !== 'single'}
				<div class="preview-card secondary">
					<h4>Secondary</h4>
					<button class="preview-btn secondary-btn">Button</button>
				</div>
				<div class="preview-card accent">
					<h4>Accent</h4>
					<button class="preview-btn accent-btn">Button</button>
				</div>
			{/if}
		</div>
	</div>
</div>

<style>
	.palette-generator {
		padding: 1.5rem;
		background: var(--color-surface);
		border-radius: 12px;
	}

	.controls {
		display: flex;
		flex-wrap: wrap;
		gap: 2rem;
		margin-bottom: 2rem;
	}

	.color-control {
		display: flex;
		align-items: center;
		gap: 0.75rem;
	}

	.color-control input[type='color'] {
		width: 48px;
		height: 48px;
		border: none;
		border-radius: 8px;
		cursor: pointer;
	}

	.scheme-selector {
		border: 1px solid var(--color-border);
		border-radius: 8px;
		padding: 1rem;
	}

	.scheme-selector legend {
		font-weight: 600;
		padding: 0 0.5rem;
	}

	.scheme-option {
		display: flex;
		align-items: flex-start;
		gap: 0.5rem;
		margin-top: 0.5rem;
		cursor: pointer;
	}

	.option-content {
		display: flex;
		flex-direction: column;
	}

	.option-content small {
		color: var(--color-foreground-muted);
		font-size: 0.75rem;
	}

	.scale-preview h3,
	.usage-preview h3 {
		margin: 0 0 1rem;
		font-size: 1rem;
	}

	.scale-row {
		display: flex;
		border-radius: 8px;
		overflow: hidden;
	}

	.scale-swatch {
		flex: 1;
		padding: 1rem 0.25rem;
		text-align: center;
		min-width: 0;
	}

	.shade-label {
		display: block;
		font-weight: 600;
		font-size: 0.75rem;
	}

	.color-hex {
		display: block;
		font-size: 0.625rem;
		font-family: monospace;
		opacity: 0.8;
	}

	.usage-preview {
		margin-top: 2rem;
	}

	.preview-cards {
		display: flex;
		gap: 1rem;
		flex-wrap: wrap;
	}

	.preview-card {
		flex: 1;
		min-width: 150px;
		padding: 1rem;
		border-radius: 8px;
		background: var(--color-background);
		border: 1px solid var(--color-border);
	}

	.preview-card h4 {
		margin: 0 0 0.75rem;
		font-size: 0.875rem;
	}

	.preview-btn {
		width: 100%;
		padding: 0.5rem 1rem;
		border: none;
		border-radius: 6px;
		font-weight: 500;
		cursor: pointer;
		background: var(--color-primary);
		color: var(--color-primary-foreground);
	}

	.preview-btn.secondary-btn {
		background: var(--color-secondary);
		color: var(--color-secondary-foreground);
	}

	.preview-btn.accent-btn {
		background: var(--color-accent);
		color: var(--color-accent-foreground);
	}
</style>

Padrão 4: Integração com Bibliotecas de Terceiros

Bibliotecas como Chart.js, D3 e APIs Canvas precisam de valores de cores em JavaScript — elas não conseguem ler variáveis CSS diretamente. Este padrão faz essa ponte.

Leitor de Cores do Tema

// src/lib/theme/chart-theme.svelte.ts
import { browser } from '$app/environment'

/**
 * Reads computed CSS custom property values for use in JS libraries.
 */
export function getThemeColors(): Record<string, string> {
	// Return sensible defaults for SSR
	if (!browser) {
		return {
			background: '#ffffff',
			surface: '#f8fafc',
			foreground: '#0f172a',
			foregroundMuted: '#64748b',
			primary: '#3b82f6',
			secondary: '#8b5cf6',
			success: '#22c55e',
			warning: '#eab308',
			error: '#ef4444',
			border: '#e2e8f0'
		}
	}

	const styles = getComputedStyle(document.documentElement)

	const getColor = (name: string) => styles.getPropertyValue(`--color-${name}`).trim() || undefined

	return {
		background: getColor('background') ?? '#ffffff',
		surface: getColor('surface') ?? '#f8fafc',
		foreground: getColor('foreground') ?? '#0f172a',
		foregroundMuted: getColor('foreground-muted') ?? '#64748b',
		primary: getColor('primary') ?? '#3b82f6',
		secondary: getColor('secondary') ?? '#8b5cf6',
		success: getColor('success') ?? '#22c55e',
		warning: getColor('warning') ?? '#eab308',
		error: getColor('error') ?? '#ef4444',
		border: getColor('border') ?? '#e2e8f0'
	}
}

/**
 * Converts hex color to rgba with opacity.
 * Useful for semi-transparent fills in charts.
 */
export function withOpacity(hexColor: string, opacity: number): string {
	const hex = hexColor.replace('#', '')
	const r = parseInt(hex.substring(0, 2), 16)
	const g = parseInt(hex.substring(2, 4), 16)
	const b = parseInt(hex.substring(4, 6), 16)
	return `rgba(${r}, ${g}, ${b}, ${opacity})`
}

/**
 * Generates an array of colors for multi-series charts.
 */
export function getChartColorPalette(count: number): string[] {
	const colors = getThemeColors()
	const palette = [colors.primary, colors.secondary, colors.success, colors.warning, colors.error]

	// Cycle through palette if more colors needed
	return Array.from({ length: count }, (_, i) => palette[i % palette.length])
}

Componente de Gráfico com Suporte a Temas

<!-- src/lib/components/ThemeAwareChart.svelte -->
<script lang="ts">
	import { onMount } from 'svelte'
	import { Chart, registerables } from 'chart.js'
	import { getThemeContext } from '$lib/theme/theme-context.svelte.js'
	import { getThemeColors, withOpacity } from '$lib/theme/chart-theme.svelte.js'

	Chart.register(...registerables)

	interface DataPoint {
		label: string
		value: number
	}

	interface Props {
		data: DataPoint[]
		title?: string
		type?: 'line' | 'bar' | 'doughnut'
	}

	let { data, title, type = 'line' }: Props = $props()

	const theme = getThemeContext()
	let canvas = $state<HTMLCanvasElement | null>(null)
	let chartInstance: Chart | null = null

	// Recreate chart when theme or data changes
	$effect(() => {
		// Access theme.mode to create dependency
		const currentMode = theme.mode
		const currentData = data

		if (!canvas) return

		// Destroy existing chart
		if (chartInstance) {
			chartInstance.destroy()
			chartInstance = null
		}

		// Get fresh colors after theme change
		const colors = getThemeColors()

		const chartConfig = {
			type,
			data: {
				labels: currentData.map((d) => d.label),
				datasets: [
					{
						label: title ?? 'Data',
						data: currentData.map((d) => d.value),
						borderColor: colors.primary,
						backgroundColor: type === 'line' ? withOpacity(colors.primary, 0.1) : colors.primary,
						borderWidth: type === 'line' ? 2 : 0,
						fill: type === 'line',
						tension: 0.4
					}
				]
			},
			options: {
				responsive: true,
				maintainAspectRatio: false,
				plugins: {
					legend: {
						display: !!title,
						labels: {
							color: colors.foreground,
							font: { family: 'system-ui' }
						}
					},
					tooltip: {
						backgroundColor: colors.surface,
						titleColor: colors.foreground,
						bodyColor: colors.foregroundMuted,
						borderColor: colors.border,
						borderWidth: 1
					}
				},
				scales:
					type !== 'doughnut'
						? {
								x: {
									ticks: { color: colors.foregroundMuted },
									grid: { color: withOpacity(colors.border, 0.5) }
								},
								y: {
									ticks: { color: colors.foregroundMuted },
									grid: { color: withOpacity(colors.border, 0.5) }
								}
							}
						: undefined
			}
		}

		chartInstance = new Chart(canvas, chartConfig)

		return () => {
			if (chartInstance) {
				chartInstance.destroy()
				chartInstance = null
			}
		}
	})
</script>

<div class="chart-wrapper">
	<canvas bind:this={canvas}></canvas>
</div>

<style>
	.chart-wrapper {
		position: relative;
		height: 300px;
		padding: 1rem;
		background: var(--color-surface);
		border: 1px solid var(--color-border);
		border-radius: 12px;
	}
</style>

Exemplo de Uso

<!-- src/routes/dashboard/+page.svelte -->
<script>
	import ThemeAwareChart from '$lib/components/ThemeAwareChart.svelte'

	const salesData = [
		{ label: 'Jan', value: 120 },
		{ label: 'Feb', value: 150 },
		{ label: 'Mar', value: 180 },
		{ label: 'Apr', value: 220 },
		{ label: 'May', value: 280 },
		{ label: 'Jun', value: 340 }
	]
</script>

<h1>Dashboard</h1>

<section class="charts-grid">
	<ThemeAwareChart data={salesData} title="Monthly Sales" type="line" />

	<ThemeAwareChart data={salesData} title="Sales by Month" type="bar" />
</section>

<style>
	.charts-grid {
		display: grid;
		grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
		gap: 1.5rem;
	}
</style>

Padrão 5: Temas Multi-Tenant para SaaS White-Label

Para aplicações SaaS onde cada cliente possui sua própria identidade visual, você precisa de um sistema completo de temas por tenant. Este padrão lida com detecção de subdomínio, integração com API de branding e considerações de SSR.

Sistema de Temas por Tenant

// src/lib/theme/tenant-theme.svelte.ts
import { browser } from '$app/environment'
import { applyDynamicColors, clearDynamicColors } from './dynamic-colors.svelte.js'

export interface TenantBranding {
	tenantId: string
	name: string
	domain: string
	logo: string
	favicon?: string
	colors: {
		primary: string
		primaryHover: string
		secondary: string
		accent: string
		headerBg: string
		headerFg: string
	}
	fonts?: {
		heading?: string
		body?: string
	}
}

// Module-level state
let currentTenant = $state<TenantBranding | null>(null)
let isLoading = $state(false)
let error = $state<string | null>(null)

const TENANT_COLOR_KEYS = [
	'primary',
	'primary-hover',
	'secondary',
	'accent',
	'header-bg',
	'header-fg'
]

/**
 * Detects tenant from current subdomain.
 * Returns null if on main domain or localhost.
 */
export function detectTenantSlug(): string | null {
	if (!browser) return null

	const hostname = window.location.hostname

	// Skip localhost
	if (hostname === 'localhost' || hostname === '127.0.0.1') {
		return null
	}

	const parts = hostname.split('.')

	// Need at least subdomain.domain.tld
	if (parts.length < 3) return null

	const subdomain = parts[0]

	// Skip common non-tenant subdomains
	if (['www', 'app', 'api', 'admin'].includes(subdomain)) {
		return null
	}

	return subdomain
}

/**
 * Loads tenant branding from API.
 */
export async function loadTenantBranding(tenantSlug: string): Promise<TenantBranding | null> {
	isLoading = true
	error = null

	try {
		const response = await fetch(`/api/tenants/${tenantSlug}/branding`)

		if (!response.ok) {
			if (response.status === 404) {
				throw new Error('Tenant not found')
			}
			throw new Error('Failed to load tenant branding')
		}

		const branding: TenantBranding = await response.json()
		applyTenantBranding(branding)

		// Cache for faster subsequent loads
		cacheTenantBranding(tenantSlug, branding)

		return branding
	} catch (e) {
		error = e instanceof Error ? e.message : 'Unknown error'
		console.error('Tenant branding error:', e)
		return null
	} finally {
		isLoading = false
	}
}

/**
 * Applies tenant branding to the application.
 */
export function applyTenantBranding(branding: TenantBranding): void {
	if (!browser) return

	currentTenant = branding

	// Apply colors
	applyDynamicColors({
		primary: branding.colors.primary,
		'primary-hover': branding.colors.primaryHover,
		secondary: branding.colors.secondary,
		accent: branding.colors.accent,
		'header-bg': branding.colors.headerBg,
		'header-fg': branding.colors.headerFg
	})

	// Apply custom fonts
	const root = document.documentElement
	if (branding.fonts?.heading) {
		root.style.setProperty('--font-heading', branding.fonts.heading)
	}
	if (branding.fonts?.body) {
		root.style.setProperty('--font-body', branding.fonts.body)
	}

	// Update page title
	document.title = `${branding.name}`

	// Update favicon
	if (branding.favicon) {
		updateFavicon(branding.favicon)
	}
}

/**
 * Initializes tenant from subdomain automatically.
 */
export async function initTenantFromSubdomain(): Promise<TenantBranding | null> {
	const slug = detectTenantSlug()
	if (!slug) return null

	// Try cache first for instant load
	const cached = getCachedTenantBranding(slug)
	if (cached) {
		applyTenantBranding(cached)
	}

	// Load fresh from API
	return loadTenantBranding(slug)
}

/**
 * Clears tenant branding, reverting to defaults.
 */
export function clearTenantBranding(): void {
	if (!browser) return

	currentTenant = null
	clearDynamicColors(TENANT_COLOR_KEYS)

	const root = document.documentElement
	root.style.removeProperty('--font-heading')
	root.style.removeProperty('--font-body')
}

/**
 * Reactive access to tenant state.
 */
export function useTenant() {
	return {
		get tenant() {
			return currentTenant
		},
		get isLoading() {
			return isLoading
		},
		get error() {
			return error
		},
		get isWhiteLabel() {
			return currentTenant !== null
		},
		get name() {
			return currentTenant?.name ?? 'App'
		},
		get logo() {
			return currentTenant?.logo ?? '/logo.svg'
		},
		init: initTenantFromSubdomain,
		load: loadTenantBranding,
		apply: applyTenantBranding,
		clear: clearTenantBranding
	}
}

// Helper functions
function updateFavicon(url: string): void {
	let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
	if (!link) {
		link = document.createElement('link')
		link.rel = 'icon'
		document.head.appendChild(link)
	}
	link.href = url
}

function cacheTenantBranding(slug: string, branding: TenantBranding): void {
	try {
		localStorage.setItem(`tenant-${slug}`, JSON.stringify(branding))
	} catch {
		/* ignore */
	}
}

function getCachedTenantBranding(slug: string): TenantBranding | null {
	try {
		const cached = localStorage.getItem(`tenant-${slug}`)
		return cached ? JSON.parse(cached) : null
	} catch {
		return null
	}
}

Suporte a SSR para Temas por Tenant

Para evitar o flash das cores padrão, injete os estilos do tenant no lado do servidor:

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

interface TenantColors {
	primary: string
	headerBg: string
	headerFg: string
}

// In production, this would fetch from your database
async function getTenantColors(slug: string): Promise<TenantColors | null> {
	// Example: fetch from database or cache
	const response = await fetch(`${process.env.API_URL}/tenants/${slug}/colors`)
	if (!response.ok) return null
	return response.json()
}

export const handle: Handle = async ({ event, resolve }) => {
	// Extract tenant from subdomain
	const host = event.request.headers.get('host') ?? ''
	const parts = host.split('.')

	// Check if this is a tenant subdomain
	if (parts.length >= 3 && !['www', 'app', 'api'].includes(parts[0])) {
		const tenantSlug = parts[0]
		const colors = await getTenantColors(tenantSlug)

		if (colors) {
			return resolve(event, {
				transformPageChunk: ({ html }) => {
					// Inject tenant colors as inline styles
					const tenantStyles = `
						<style id="tenant-theme">
							:root {
								--color-primary: ${colors.primary};
								--color-header-bg: ${colors.headerBg};
								--color-header-fg: ${colors.headerFg};
							}
						</style>
					`
					return html.replace('</head>', `${tenantStyles}</head>`)
				}
			})
		}
	}

	return resolve(event)
}

Layout Multi-Tenant

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { onMount } from 'svelte'
	import { useTenant } from '$lib/theme/tenant-theme.svelte.js'
	import ThemeProvider from '$lib/theme/ThemeProvider.svelte'

	let { children } = $props()

	const tenant = useTenant()

	onMount(() => {
		tenant.init()
	})
</script>

<ThemeProvider>
	<div class="app-layout">
		<header class="app-header">
			<a href="/" class="brand">
				<img src={tenant.logo} alt="{tenant.name} logo" class="brand-logo" />
				<span class="brand-name">{tenant.name}</span>
			</a>

			<nav class="header-nav">
				<slot name="nav" />
			</nav>
		</header>

		<main class="app-main">
			{@render children()}
		</main>

		<footer class="app-footer">
			<p>© {new Date().getFullYear()} {tenant.name}. All rights reserved.</p>
		</footer>
	</div>
</ThemeProvider>

<style>
	.app-layout {
		min-height: 100vh;
		display: flex;
		flex-direction: column;
	}

	.app-header {
		display: flex;
		align-items: center;
		justify-content: space-between;
		padding: 0.75rem 1.5rem;
		background-color: var(--color-header-bg, var(--color-primary));
		color: var(--color-header-fg, var(--color-primary-foreground));
	}

	.brand {
		display: flex;
		align-items: center;
		gap: 0.75rem;
		text-decoration: none;
		color: inherit;
	}

	.brand-logo {
		height: 36px;
		width: auto;
	}

	.brand-name {
		font-family: var(--font-heading, system-ui);
		font-weight: 600;
		font-size: 1.125rem;
	}

	.app-main {
		flex: 1;
		padding: 2rem;
	}

	.app-footer {
		padding: 1.5rem;
		text-align: center;
		background: var(--color-surface);
		border-top: 1px solid var(--color-border);
		color: var(--color-foreground-muted);
		font-size: 0.875rem;
	}
</style>

Erros Comuns

Usar propriedades CSS via JavaScript para temas estáticos

// Don't do this for light/dark switching
applyDynamicColors({
	background: isDark ? '#0f172a' : '#ffffff'
	// ... more colors
})

CORREÇÃO: Use seletores CSS em vez disso

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

Esquecer os fallbacks de SSR

// This crashes on server
const styles = getComputedStyle(document.documentElement)

CORREÇÃO: Sempre verifique se está no navegador

if (!browser) return defaultColors
const styles = getComputedStyle(document.documentElement)

Não limpar cores dinâmicas

// Colors persist even after component unmounts
applyDynamicColors({ primary: userColor })

CORREÇÃO: Limpe as cores quando apropriado

onDestroy(() => {
	clearDynamicColors(['primary'])
})

Considerações de Desempenho

Propriedades CSS dinâmicas têm implicações de desempenho:

Agrupe as atualizações — Use uma única chamada applyDynamicColors() em vez de múltiplas chamadas setProperty(). Cada alteração de propriedade pode disparar o recálculo de estilos.
Evite em animações — Não atualize propriedades CSS customizadas em loops de animação. Use transições CSS ou a Web Animations API em vez disso.
Faça cache de cores computadas — Se estiver lendo cores com frequência (por exemplo, para canvas), armazene os valores em cache em vez de chamar getComputedStyle() repetidamente.
Caminho crítico do SSR — Para aplicações white-label, injete as cores críticas do tenant no lado do servidor para evitar mudanças de layout.

Principais Conclusões

CSS em primeiro lugar ainda é o padrão — Use propriedades CSS via JavaScript somente quando as cores são genuinamente desconhecidas em tempo de build.
Cinco casos de uso legítimos — Personalização do usuário, temas orientados por API, computação em tempo de execução, integração com terceiros e SaaS white-label.
Sempre trate o SSR — Verifique browser antes de acessar document e forneça valores padrão razoáveis.
Faça cache de forma agressiva — Armazene cores dinâmicas no localStorage para evitar flash em visitas repetidas.
Limpe adequadamente — Remova propriedades dinâmicas quando elas não forem mais necessárias.
Agrupe suas atualizações — Minimize os recálculos de estilo atualizando múltiplas propriedades de uma só vez.

Leitura Adicional

Recursos Externos

Documentação do Chroma.js — Biblioteca profissional de manipulação de cores
Temas no Chart.js — Documentação oficial de cores do Chart.js
Diretrizes de Contraste WCAG — Requisitos de acessibilidade para contraste de cores

Quando as Variáveis CSS Sozinhas Não São Suficientes

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

Compreendendo o Limite entre Tempo de Compilação e Tempo de Execução

Caso 1: Cores Personalizáveis pelo Usuário — O Problema do Infinito

Caso 2: Temas Orientados por API — O Problema dos Dados Externos

Caso 3: Computação de Cores em Tempo de Execução — O Problema da Matemática

Caso 4: Integração com Bibliotecas de Terceiros — O Problema do Mundo Apenas em JavaScript

Caso 5: Tematização Multi-Tenant White-Label SaaS — O Problema da Identidade Desconhecida

Resumo: O Framework de Decisão

Utilitários Principais

Padrão 1: Seletor de Cores Personalizável pelo Usuário

Utilitários de Matemática de Cores

O Componente Seletor de Cores

Usando o Personalizador de Cores

Padrão 2: Temas Orientados por API

Usando Temas Orientados por API

Padrão 3: Computação de Cores em Tempo de Execução com Chroma.js

Configuração

Gerador de Paleta

Componente Gerador de Paleta

Padrão 4: Integração com Bibliotecas de Terceiros

Leitor de Cores do Tema

Componente de Gráfico com Suporte a Temas

Exemplo de Uso

Padrão 5: Temas Multi-Tenant para SaaS White-Label

Sistema de Temas por Tenant

Suporte a SSR para Temas por Tenant

Layout Multi-Tenant

Erros Comuns

Usar propriedades CSS via JavaScript para temas estáticos

Esquecer os fallbacks de SSR

Não limpar cores dinâmicas

Considerações de Desempenho

Principais Conclusões

Leitura Adicional

Artigos Relacionados

Recursos Externos