cybercore-systems/cybercore-signer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(ui): document native windows titlebar behavior in dark OS mode
CI Pipeline / Build & Verify (Linux x86_64) (push) Canceled after 0s
Details
CI Pipeline / Build & Verify (Windows) (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
Claudecio Martins
2026-10-20 21:33:39 -03:00
parent e20a52d3b2
commit 9f1bc289ee
1 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ui-troubleshooting.md
+16
View File
@@ -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.