Pular para conteúdo

MVP 2 - Sistema de Tema Claro/Escuro

Atualizado: 2026-05-18 Status: canonico para planejamento MVP2 Issue raiz: auraxis-platform#697

Visao executiva

O Auraxis deve suportar tema claro e escuro em Web e App sem duplicar design por tela. O tema claro passa a ser o padrao para novos usuarios, enquanto o tema escuro existente continua como opcao de primeira classe.

A direcao visual deve preservar a identidade atual, com azul/ciano como sinal de tecnologia financeira, verdes para progresso e receitas, vermelho para risco/despesa, amarelo para alerta e tons neutros frios para leitura. A mudanca principal e sair de uma implementacao dark-first com cores fixas para um Design System baseado em tokens semanticos.

Inspiracoes

As referencias abaixo nao devem ser copiadas literalmente. Elas ajudam a calibrar maturidade visual, confianca e leitura para produto financeiro.

Referencia O que absorver O que evitar
TradeMap Densidade informacional, graficos claros, uso de cor para dados financeiros. Interface excessivamente tecnica para usuarios iniciantes.
B3 Seriedade institucional, contraste, uso disciplinado de azul e superficies claras. Linguagem visual corporativa demais para produto B2C.
Mobills Clareza de beneficios, tom acessivel e organizacao de financas pessoais. Paleta muito promocional ou pouco alinhada ao app atual.

Principios

  1. Tema claro por padrao. Novos usuarios entram no tema claro, com opcao de usar system ou dark.
  2. Dark sem regressao. A experiencia escura atual deve continuar visualmente confortavel, especialmente nas telas de dashboard, transacoes e insights.
  3. Tokens semanticos antes de CSS por tela. Componentes devem usar surface, text, border, accent, success, danger e nao valores fixos.
  4. Dados financeiros precisam de legibilidade. Graficos, tabelas e valores monetarios devem manter contraste e significado em ambos os temas.
  5. Acessibilidade e obrigatoria. Texto essencial deve mirar WCAG AA. Cor nao pode ser o unico indicador de status.
  6. Sem paleta de uma nota so. O app nao deve virar uma variacao infinita de azul. Cores funcionais precisam aparecer com intencao.

Modos suportados

Modo Comportamento
light Usa tokens claros explicitamente. E o default para novos usuarios.
dark Usa tokens escuros explicitamente. Deve preservar a identidade atual.
system Segue prefers-color-scheme do dispositivo/navegador.

Preferencia deve ser persistida por usuario quando autenticado e por dispositivo quando guest. O carregamento inicial nao deve piscar entre temas.

Paleta clara recomendada

Token Valor Uso
bg.canvas #F4F8FB Fundo geral do app.
bg.app #EFF5FA Areas amplas e app shell.
bg.surface #FFFFFF Cards, paineis e tabelas.
bg.elevated #F8FBFF Modais, popovers e surfaces destacadas.
text.primary #0A1628 Titulos e conteudo principal.
text.secondary #263A56 Labels e textos de apoio.
text.muted #5D6F89 Metadados e textos auxiliares.
border.subtle #D8E3EF Bordas discretas.
brand.primary #087FA7 CTA principal, links e highlights.
brand.primary.soft #D8F3FB Fundo de badges e selecao leve.
positive #087F5B Receitas, sucesso e crescimento.
negative #C2414D Despesas, risco e erro.
warning #B7791F Alerta e pendencias.
info #2563EB Informacao neutra.

Paleta escura recomendada

Token Valor Uso
bg.canvas #05080D Fundo geral dark.
bg.app #07111D App shell e faixas principais.
bg.surface #0F1B2D Cards e tabelas.
bg.elevated #15233A Modais e popovers.
text.primary #F4F8FF Titulos e conteudo principal.
text.secondary #CBD7EA Labels e textos de apoio.
text.muted #8EA0BB Metadados.
border.subtle #25334A Bordas discretas.
brand.primary #4CC9F0 CTA principal e links.
brand.primary.soft #0E3546 Fundo de badges e selecao leve.
positive #41D6A4 Receitas e sucesso.
negative #FF6B7A Despesas e erro.
warning #F2B94B Alertas.
info #7EA7FF Informacao neutra.

Tokens semanticos obrigatorios

Grupo Tokens minimos
Fundo canvas, app, surface, surfaceMuted, elevated, overlay
Texto primary, secondary, muted, inverse, disabled, onAccent
Bordas subtle, strong, focus, danger, success
Acao primary, primaryHover, primaryActive, secondary, ghost
Estados success, successBg, danger, dangerBg, warning, warningBg, info, infoBg
Dados income, expense, balance, investment, debt, forecast, grid, axis

Regras Web

  • O auraxis-web deve centralizar tema no provider global, usando NConfigProvider e CSS variables.
  • Componentes base devem consumir tokens, nao cores fixas.
  • O app shell, rotas auth, tabelas, modais, selects, charts e toasts devem ser migrados antes das telas especificas.
  • O toggle de tema deve oferecer Claro, Escuro e Sistema, com icones e labels acessiveis.
  • Layouts densos, como transacoes, devem usar contraste de tabela suficiente sem parecerem planilhas frias demais.
  • Graficos devem usar paletas distintas por serie e manter legibilidade em light/dark.

Regras App

  • O auraxis-app deve alinhar tokens Tamagui auraxis_light e auraxis_dark ao DS canonico.
  • O tema claro tambem deve ser default no mobile.
  • O App pode ajustar valores para plataforma nativa, mas deve manter equivalencia semantica.
  • Snapshots e smoke iOS/Android devem validar telas core nos dois temas.

Acessibilidade

Checklist minimo por PR de tema:

  • Texto essencial com contraste AA.
  • Focus ring visivel em light e dark.
  • Estados de erro/sucesso com icone, texto ou padrao visual alem de cor.
  • Tabelas com hover/selected legiveis.
  • Modais com overlay suficiente e leitura clara.
  • Graficos com legenda, labels ou tooltips que nao dependem apenas de cor.

Ordem de implementacao

  1. auraxis-web#885 - Design System claro/escuro com default claro.
  2. auraxis-web#886 - Naive UI, app shell e componentes base.
  3. auraxis-web#887 - Telas core em claro/escuro.
  4. auraxis-app#429 - Tokens App alinhados ao DS canonico.
  5. auraxis-app#430 - Telas core App em claro/escuro.

Criterios globais de aceite

  • Tema claro e default para novos usuarios.
  • Usuario consegue escolher system, light e dark.
  • Dark theme atual nao regride.
  • As telas core possuem screenshots light/dark em desktop e mobile quando aplicavel.
  • O Web e o App apontam para esta pagina como fonte canonica.
  • Nenhuma implementacao nova usa hardcode de cor quando token semantico existir.

Riscos

Risco Mitigacao
Regressao visual no dark theme Screenshots antes/depois e PRs pequenos por camada.
Hardcodes espalhados rg por cores hex/RGB e lint progressivo.
Tema claro sem contraste suficiente Checklist WCAG AA e revisao visual em telas densas.
Flicker no carregamento Resolver preferencia antes da hidratacao visual.
Divergencia Web/App Tokens canonicos nesta pagina e snapshots por plataforma.