Dark Mode vs Light Mode — Como Lidar com os Dois em um Único DESIGN.md

Dark mode não é mais opcional. Usuários esperam. Sistemas operacionais já vêm com ele ativado. E se o seu AI agent gera um componente que só funciona em light mode, parabéns — você acabou de dobrar seu trabalho de revisão.

A parte difícil não é dar suporte a dark mode. É codificar os dois modos num arquivo DESIGN.md que continue legível e não confunda seu agent com lógica condicional que ele não consegue interpretar.

Testei várias abordagens no último ano. A maioria é ruim. Aqui vai o que realmente funciona.

Por Que Isso É Mais Difícil Do Que Parece

A abordagem ingênua: definir duas paletas de cores e mandar o agent usar a certa. O problema é que agents não têm contexto de runtime. Eles não sabem qual modo o usuário vai ver. Geram código estático. A troca de modo acontece no CSS ou no theme provider do seu framework.

Então seu DESIGN.md precisa descrever um sistema que funciona nos dois modos — não dois sistemas separados.

A Abordagem de Cores Semânticas

Em vez de definir cores pelo valor, defina pelo papel que exercem:

colors:
  # Semantic tokens — these flip between modes
  surface: "var(--surface)"        # white in light, #0f172a in dark
  surface-alt: "var(--surface-alt)" # #f8fafc in light, #1e293b in dark
  text: "var(--text)"              # #0f172a in light, #f1f5f9 in dark
  text-muted: "var(--text-muted)"  # #64748b in both
  border: "var(--border)"          # #e2e8f0 in light, #334155 in dark
  primary: "#2563eb"               # stays the same in both modes
  primary-text: "#ffffff"          # stays the same in both modes

Depois, na seção descritiva do seu DESIGN.md, explique o mapeamento:

## Theming

This design system uses CSS custom properties for mode switching.
The agent should always use semantic token names (surface, text, border),
never raw hex values for backgrounds or text colors.

Light mode values:
- --surface: #ffffff
- --surface-alt: #f8fafc
- --text: #0f172a
- --border: #e2e8f0

Dark mode values:
- --surface: #0f172a
- --surface-alt: #1e293b
- --text: #f1f5f9
- --border: #334155

Primary color (#2563eb) is mode-independent.

O agent gera componentes usando var(--surface) em vez de #ffffff. A troca de modo acontece no CSS, não no código do componente. Separação limpa.

E o Contraste?

É aqui que a maioria das implementações de dark mode quebra. Uma cor com ratio de contraste 4.5:1 contra branco pode ter 2:1 contra cinza escuro. Seu DESIGN.md precisa deixar isso explícito:

## Do's and Don'ts
- Do test all text colors against both surface values
- Don't use text-muted for small text (< 14px) — insufficient contrast in dark mode
- Do use primary color for interactive elements in both modes (it passes WCAG AA against both surfaces)
- Don't use pure black (#000000) as dark mode surface — too harsh, causes halation

Sombras e Elevação

Sombras se comportam de forma diferente em dark mode. Um box-shadow que adiciona profundidade sutil em fundos brancos fica invisível em fundos escuros. Algumas abordagens:

Opção 1: Trocar sombras por bordas em dark mode. Diga ao agent:

## Elevation
- Light mode: use box-shadow for card elevation
- Dark mode: use 1px border with --border color instead of shadows

Opção 2: Usar sombras mais claras em dark mode. Menos comum, mas funciona bem pra estilos glassmórficos:

## Elevation
- Light: box-shadow: 0 1px 3px rgba(0,0,0,0.1)
- Dark: box-shadow: 0 1px 3px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.05)

Comportamento dos Agents na Prática

Quando passo pro Claude Code um DESIGN.md com tokens semânticos e documentação clara de modos:

• Ele usa var(--surface) consistentemente em vez de cores hardcoded
• Adiciona variantes dark: no Tailwind quando o DESIGN.md menciona Tailwind
• Às vezes esquece de tratar sombras de forma diferente por modo (precisa de lembrete explícito)
• Nunca gera lógica de toggle de modo a menos que você peça — só faz componentes que funcionam nos dois

O ponto-chave: agents são bons em seguir sistemas de tokens. São ruins em inferir comportamento condicional. Seja explícito sobre o que muda entre modos e o que não muda.

O DESIGN.md Mínimo Viável pra Dark Mode

Se você quer adicionar suporte a dark mode num DESIGN.md existente sem reescrever tudo, inclua esta seção:

## Dark Mode

This system supports light and dark modes via CSS custom properties.
Always use semantic color names from the tokens above.
Never hardcode background or text colors.

Key differences in dark mode:
- Surfaces get darker (not inverted — use the dark palette, not white-on-black)
- Borders become more visible (lighter opacity)
- Shadows become less visible (use borders for elevation instead)
- Primary accent color stays the same
- Images may need reduced brightness (add opacity: 0.9 in dark mode)

São 10 linhas. Suficiente pro agent acertar 90% dos casos.

Explore Design Systems Prontos pra Dark Mode

A biblioteca de DESIGN.md inclui sistemas pensados pra ambos os modos:

• Suporte completo dark/light: procure por ”✓ Full / ✓ Full” no campo Light/Dark
• Sistemas dark-only: Cyber-Tribal, Steampunk Vitoriano
• Sistemas light-only: Minimalism & Swiss Style, Art Nouveau Florido

Escolha um que combine com seu produto e adapte a seção de theming pro seu framework.