From 9f1bc289eeb9c00d34f5ae8fb7989bea1603ceea Mon Sep 17 00:00:00 2001 From: Claudecio Martins Date: Tue, 20 Oct 2026 21:33:39 -0300 Subject: [PATCH] docs(ui): document native windows titlebar behavior in dark OS mode --- docs/ui-troubleshooting.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/ui-troubleshooting.md b/docs/ui-troubleshooting.md index d901475..906e8fd 100644 --- a/docs/ui-troubleshooting.md +++ b/docs/ui-troubleshooting.md @@ -77,3 +77,19 @@ Fica estabelecido como regra obrigatória de desenvolvimento no `cybercore-ui`: O teste de arquitetura [`DesignTokenGuardrailTest.java`](file:///var/www/cybercore/cybercore-signer/modules/cybercore-ui/src/test/java/br/com/cybercore/signer/ui/theme/DesignTokenGuardrailTest.java) atua como barreira de compilação contínua: - Varre todos os arquivos `.java` no módulo `cybercore-ui` e reprova automaticamente o build se qualquer chamada `setStyle()` contiver propriedades ou valores de cor. - Valida matematicamente a relação de contraste WCAG AA (mínimo de 4.5:1 para texto normal) em todas as combinações de tokens de texto sobre superfície/fundo. +- Assegura ausência de seletores ou classes residuais de temas escuros (`.theme-dark`, `AppTheme`, `isDark()`). + +--- + +## 5. Comportamento da Barra de Título Nativa no Windows (DWM em Modo Escuro) + +### Diagnóstico Operacional +Quando o sistema operacional Windows 10/11 está configurado no "Modo Escuro do Sistema" (*Personalização > Cores > Escolher o modo: Escuro*), o gerenciador de janelas do sistema operacional (**Desktop Window Manager — DWM**) aplica automaticamente o atributo `DWMWA_USE_IMMERSIVE_DARK_MODE` na moldura não-cliente da janela nativa (`HWND`). + +Como o CyberCore Signer utiliza decoração nativa padrão (`StageStyle.DECORATED`) para preservar o comportamento esperado pelo usuário empresarial — incluindo cantos arredondados, atalhos de teclado nativos, suporte a múltiplos monitores com DPIs distintos e os *Snap Layouts* do Windows 11 — a barra de título nativa é desenhada pelo Windows em tom escuro, enquanto o conteúdo da janela exibe o tema claro unificado da aplicação. + +### Diretriz de Arquitetura (Não Forçar) +Em estrita conformidade com as diretrizes do projeto (Regras 2 e 23): +1. **Não forçar a barra de título:** Evita-se o uso de hacks de baixo nível via JNA/JNI para sobrescrever o DWM do Windows ou janelas não decoradas (`UNDECORATED`), o que causaria quebra de acessibilidade e perda de recursos nativos do sistema. +2. **Harmonia Visual:** A moldura do Windows atua como moldura de sistema e o conteúdo claro do CyberCore Signer permanece legível, íntegro e em total conformidade com a especificação de interface. +