coastdigitalgroup/coastai-skills

Sistema de Design de Tema Escuro

Propósito

A skill Sistema de Design de Tema Escuro fornece uma metodologia para traduzir interfaces web de tema claro em suas contrapartes de tema escuro. Projetar um modo escuro não é uma simples questão de inverter valores de cores. Fazer isso quebra as metáforas físicas de iluminação, causa fadiga visual severa e cria interfaces ilegíveis e com alto brilho.

Este sistema estabelece as regras visuais e espaciais do design de baixa luminosidade:

• Inversão de Elevação: Transmitir profundidade no modo escuro clareando os fundos de superfícies elevadas, em vez de usar sombras escuras.
• Dessaturação de Cores: Adaptar cores de destaque vibrantes da marca e semânticas para níveis de baixo contraste, a fim de evitar "vibração" visual e cansaço ocular.
• Prevenção de Contraste e Halo: Evitar combinações de branco puro sobre preto que causam brilho extremo (halo) para leitores com astigmatismo ou dislexia, optando por tons de branco e preto suaves.
• Calibração de Peso Tipográfico: Neutralizar a "irradiação" (a ilusão de ótica onde texto claro em fundo escuro parece mais espesso e em negrito do que texto escuro em fundo claro).
• Atenuação de Mídia: Adaptar imagens, vídeos e diagramas vetoriais para que não "ceguem" visualmente o usuário em condições de baixa luminosidade.

---

Casos de Uso

• Projetando Kits de UI de Tema Duplo: Estabelecer a arquitetura de tokens de design semântico para um sistema que suporte nativamente os modos claro e escuro.
• Redesenhando Painéis SaaS e Ambientes de Leitura: Criar interfaces de baixa fadiga otimizadas para visualização de longa duração, fluxos de trabalho de desenvolvedor ou uso noturno.
• Auditando Temas Escuros Inacessíveis: Identificar e corrigir problemas de contraste, acentos vibrantes, pesos de texto ilegíveis e ativos de mídia ofuscantes.
• Fornecendo Especificações de Entrega Multi-Tema: Gerar especificações limpas e prontas para o desenvolvedor mostrando exatamente como os elementos se comportam em diferentes temas.

---

Quando NÃO Usar

• Ambientes Escuros por Padrão (Cinematográficos): Se um aplicativo é exclusivamente escuro (ex.: Spotify, Netflix ou plataformas de streaming de jogos) e nunca suportará um tema claro. Um sistema de design de tema duplo é uma sobrecarga desnecessária neste caso.
• Microcampanhas Altamente Expressivas / Artísticas: Páginas de destino independentes onde a disrupção visual, paletas extremamente saturadas ou branding artístico superam o conforto de visualização de longa duração ou regras estritas de acessibilidade.
• Frameworks Legados Estritamente Estáticos: Aplicações cujas arquiteturas de front-end não podem carregar estilos dinâmicos ou não possuem suporte a variáveis CSS, impedindo a adaptação sistemática do tema.

---

Entradas

1. Paleta Central do Modo Claro e Estilos da Marca: As cores primárias existentes da marca, cores secundárias, escalas tipográficas e tokens de espaçamento fluido.
2. Inventário de Componentes e Hierarquia de Profundidade: Uma lista abrangente dos layouts de página e camadas de UI (fundos, barras laterais, cartões, modais, menus suspensos).
3. Contexto do Ambiente de Iluminação: Os arredores físicos típicos do usuário alvo (ex.: leitura noturna na cama vs. um chão de fábrica industrial bem iluminado).
4. Alvo de Acessibilidade: Padrão WCAG 2.2 AA (mínimo) ou AAA (aprimorado), incluindo considerações para astigmatismo e daltonismo.

---

Saídas

1. Mapa de Token Semântico Unificado: Uma especificação sistemática que liga diretamente os valores do modo claro aos seus equivalentes correspondentes no modo escuro.
2. Escala de Superfície Baseada em Elevação: Uma escala de 5 a 6 etapas definindo como os valores de fundo da superfície clareiam à medida que flutuam mais alto no eixo Z.
3. Paleta de Acento Dessaturada: Um conjunto calibrado de cores de status primárias, secundárias e semânticas dessaturadas para fundos escuros.
4. Correções de Folha de Estilo Tipográfica: Regras específicas para peso da fonte, espaçamento entre letras e ajustes de cor do texto para neutralizar o efeito de irradiação.
5. Especificações de Atenuação de Mídia: Técnicas CSS e HTML para reduzir o brilho/contraste de imagens e ajustar gráficos vetoriais.

---

Fluxo de Trabalho

1. Definir a Base: Selecionar Preto Suave e Branco Suave

Evite #000000 (preto puro) absoluto para fundos e #FFFFFF (branco puro) absoluto para texto do corpo.

• O Fundo Base: Estabeleça um neutro escuro e matizado (ex.: ardósia profunda, carvão ou cinza-azulado escuro entre #121212 e #1A1A1A). Isso reduz o cansaço ocular, evita a cintilação da tela e retorna alguma profundidade visual.
• A Base do Texto: Escolha um branco suave ou cinza claro (ex.: #E2E8F0 ou #EAEAEA com uma opacidade de 85% a 90%). Isso garante contraste confortável sem causar halo (dispersão de luz no olho do leitor).

2. Traduzir Profundidade via Clareamento por Elevação

Em um tema claro, indicamos que um elemento está elevado projetando uma sombra mais escura. Em um tema escuro, uma sombra escura é invisível contra um fundo escuro.

• O Princípio do Clareamento: À medida que um elemento sobe mais alto no eixo Z, ele se aproxima da fonte de luz ambiente virtual e se torna mais claro, não mais escuro.
• Crie uma Escala de Superfície de Elevação:
  • Nível 0 (Base da Tela): Cor mais escura (ex.: #121212).
  • Nível 1 (Cartão/Item de Lista): Ligeiramente mais claro (ex.: #1D1D1D).
  • Nível 2 (Cabeçalho Fixo/Ação Flutuante): Ainda mais claro (ex.: #242424).
  • Nível 3 (Caixa Modal/Diálogo): Superfície mais clara (ex.: #2C2C2C).
• Apoie com Sombras Suaves: Use sombras muito sutis, cinza escuro ou preto translúcido em camadas elevadas (ex.: rgba(0, 0, 0, 0.5)) para fornecer separação em superfícies maiores que ficam sobre itens de Nível 1.

3. Calibrar e Dessaturar Cores de Acento

Cores altamente saturadas que parecem vibrantes em uma tela branca "vibrarão" em uma tela escura, criando fadiga visual severa e falhando nos testes de contraste.

• Dessature os Acentos da Marca: Desloque as cores da marca para equivalentes mais claros, suaves e pastéis. (Ex.: um azul primário vibrante #0055FF em fundo claro deve mapear para um azul dessaturado #66A3FF ou #80B3FF no escuro).
• Mantenha Acentos Seguros de Contraste: Verifique se as cores de acento dessaturadas em superfícies escuras ainda atendem aos padrões WCAG 2.2 AA (proporção mínima de 4,5:1 para texto, 3:1 para estados interativos).
• Evite Grandes Blocos Saturados: Em vez de renderizar botões ou banners inteiros em cores sólidas saturadas, use-as com moderação—como links de texto, bordas ou indicadores sutis.

4. Ajustar a Tipografia para Irradiação Óptica

Texto claro em fundo escuro sofre de irradiação—o texto branco parece "sangrar" na escuridão circundante, fazendo as letras parecerem mais ousadas, mais espessas e mais próximas do que suas equivalentes claro-sobre-escuro.

• Calibração de Peso: Reduza o peso da fonte dos títulos em negrito do tema claro em um nível (ex.: mude 700 (Negrito) para 600 (Semi-Negrito) ou mesmo 500 (Médio) no escuro).
• Calibração de Espaçamento entre Letras: Aumente o espaçamento entre letras (tracking) ligeiramente para o texto do corpo no modo escuro (ex.: letter-spacing: 0.02em; ou 0.015em;) para evitar que letras individuais se misturem.
• Hierarquia Secundária/Terciária: Controle a hierarquia ajustando a opacidade da cor do texto, não apenas o tamanho. Use opacity: 0.87 para corpo de alta prioridade, opacity: 0.60 para texto auxiliar secundário e opacity: 0.38 para indicadores desabilitados.

5. Adaptar Mídia e Conteúdo Rico

Fotos, gráficos e diagramas não modificados podem arruinar uma experiência de modo escuro perfeita, cegando o usuário com brancos brilhantes e de alto contraste.

• Atenuação de Fotos: Aplique uma redução sutil de brilho e contraste a fotografias para mesclá-las na atmosfera de baixa luminosidade.

  [data-theme="dark"] img:not(.avatar) {
    filter: brightness(0.85) contrast(0.95);
  }
  

• Ativos Vetoriais e Ilustrações: Troque as cores de fundo brilhantes em SVGs ou use filtros SVG para inverter caminhos específicos. Para gráficos ilustrativos, use <picture> com consultas de mídia para carregar ativos de tema escuro personalizados.
• Visualizações de Dados: Redefina as séries de cores do gráfico para usar linhas dessaturadas e preenchimentos de área semitransparentes que permaneçam legíveis sem luminância excessiva.

---

Regras de Decisão

A Regra de Clareamento por Elevação

Ao estabelecer o fundo de um contêiner visual, consulte o nível de elevação. Nunca faça um modal ou menu suspenso elevado mais escuro do que o fundo da página abaixo dele.

Nível de Elevação	Fundo do Modo Claro	Fundo do Modo Escuro	Indicação de Elevação Implícita
Nível 0 (Tela)	#FFFFFF (Branco) ou #F8F9FA	#121212 (Preto suave)	Nível do solo / base
Nível 1 (Cartão/Seção)	#FFFFFF (Branco) com borda	#1E1E1E (Superfície 1)	Flutuando 1-2dp
Nível 2 (Cabeçalho/Fixo)	#FFFFFF ou matiz translúcido sutil	#252525 (Superfície 2)	Flutuando 4-8dp
Nível 3 (Modal/Diálogo)	#FFFFFF com sombra pesada	#2D2D2D (Superfície 3)	Flutuando 12-24dp

O Limite de Saturação

• Acentos usados como fundos para estados interativos (ex.: um contêiner de chip secundário) devem ter uma saturação de 10% a 15% no modo escuro.
• Acentos usados como texto de primeiro plano ou ícones devem ter uma saturação de 40% a 60% para garantir que se destaquem sem vibrar contra a superfície escura.

O Buffer de Contraste

Como o brilho da tela e as telas de baixa qualidade degradam a visibilidade do modo escuro mais severamente do que o modo claro, sempre busque uma proporção de contraste de 5.0:1 no texto do corpo do modo escuro (excedendo o mínimo WCAG 4.5:1) para atuar como um buffer para ambientes físicos ruins.

---

Restrições

• Acessibilidade (WCAG AA): Elementos de texto devem atingir pelo menos 4,5:1 de contraste (3:1 para texto grande). Bordas de UI, anéis de foco e ícones funcionais devem atingir pelo menos 3:1 de contraste. Os indicadores de foco devem permanecer altamente visíveis e não ser sufocados pelos brilhos do fundo escuro (WCAG 2.2 SC 2.4.11).
• Adaptação a Brilho Responsivo: As cores do texto devem ser resistentes a alto brilho ambiente (como telas de celular usadas ao ar livre), o que significa que níveis de contraste mínimos absolutos devem ser evitados.
• Nenhuma Hierarquia Apenas por Cor: Não confie puramente no matiz de uma cor dessaturada para transmitir status (ex.: aviso vs. erro em gráficos). Integre padrões distintos, rótulos de texto ou iconografia.

---

Padrões Comuns de Falha

• O "Inversor Literal": Executar um filtro de inversão de cores automatizado em um tema claro. Isso transforma elementos elevados do modo claro com sombras escuras em elementos afundados do modo escuro com anéis brancos brilhantes, quebrando todos os modelos de iluminação naturais.
• O Pesadelo "Néon Vibrante": Colocar cores de marca totalmente saturadas (ex.: #00FF00 ou #FF00FF) diretamente em um fundo preto puro. Isso desencadeia fadiga visual, tornando o texto quase impossível de ler por mais de alguns segundos.
• O Extremo OLED (Brilho Preto Puro): Usar texto #FFFFFF diretamente em fundos #000000. Isso cria um efeito severo de halo/brilho em muitas telas, reduzindo a velocidade de leitura e causando cansaço ocular.
• O Anel de Foco Desaparecido: Projetar um belo modo escuro, mas deixar os indicadores de foco padrão do navegador, que geralmente são azul escuro e se tornam completamente invisíveis em fundos de ardósia escura.
• A Ilustração Ofuscante: Criar uma UI escura perfeita, mas deixar fundos brancos de alto contraste e puros dentro de gráficos SVG, logotipos ou ícones ilustrativos.

---

Critérios de Validação

• Valores Base: Nenhum preto puro absoluto (#000) é usado para o fundo principal da tela, e nenhum branco puro absoluto (#FFF) é usado para o texto do corpo.
• Modelo de Elevação: As superfícies tornam-se progressivamente mais claras (valor de luminosidade mais alto) à medida que se elevam no eixo Z.
• Verificação de Contraste: Cada cor de texto, incluindo texto auxiliar suave, atende ou excede a proporção de contraste WCAG 2.2 AA (4,5:1 normal, 3:1 grande).
• Acentos Não Vibrantes: Cores de acento e status são dessaturadas para variar entre 10% e 60% de saturação dependendo da aplicação, evitando vibração visual.
• Visibilidade de Foco: Elementos interativos possuem indicadores de foco de alto contraste e distintos, claramente visíveis contra superfícies escuras.
• Calibração Tipográfica: O texto em negrito é ajustado (reduzido em um nível de peso ou com tracking aumentado) para compensar a irradiação.
• Filtro de Mídia: Um mecanismo responsivo (filtros CSS ou troca de ativos escuros) é especificado para reduzir o brilho e o contraste de mídia rica e ativos vetoriais.