Qt/QML desktop UI with web-app polish

Missão: construir UI desktop nativa em Qt 6 / QML, com refinamento visual, fluidez, acessibilidade e padrões de UX de produtos desktop modernos. Referências visuais são inspiração, não exigências de tecnologia nem de estilo.

Quando ativar

Use esta skill quando a tarefa envolver criação/refatoração de interface com Qt Quick, QML, Qt Quick Controls ou PySide6/PyQt6 + QML: dashboard, IDE, painel de configurações, aplicativo de produtividade, biblioteca de componentes, design tokens, temas, animações, acessibilidade e layout responsivo.

Não a use para converter aplicações web desnecessariamente nem para impor QML a um projeto de Qt Widgets sem solicitação explícita de migração.

Procedimento obrigatório

1. Inspecione antes de alterar. Leia arquivos de build (CMakeLists.txt, pyproject.toml, .pro), main.cpp/bootstrap Python, QML existentes, assets, convenções e versão instalada do Qt. Descubra sistema operacional e sistema de navegação. Preserve as integrações e a arquitetura do projeto. Se for um projeto novo, tome como base Qt 6.5+, CMake e Qt Quick Controls Basic; adapte à versão do ambiente.
2. Defina o produto visual. Determine público, tarefa central da tela, estrutura de informação e uma direção de design (p.ex. developer tool, productivity workspace, data console). Não produza o "dashboard genérico" quando o domínio pede outra metáfora. Se a solicitação for aberta, faça uma escolha visual coerente sem bloquear o trabalho por perguntas dispensáveis.
3. Estabeleça tokens antes dos componentes. Cores semânticas, tipografia, espaçamentos (escala de 4/8), raios, bordas, estados, densidade e motion. Use um singleton QML (Theme.qml) para tokens compartilhados. Leia references/design-language.md.
4. Construa a composição macro antes dos detalhes. Determine sidebar/nav, cabeçalho, hierarquia, área de conteúdo, scroll e estados vazios. Priorize alinhamento, espaçamento e legibilidade. Faça uma tela principal convincente antes de multiplicar páginas.
5. Implemente com controles reais. Prefira QtQuick.Controls.Basic para controles redesenhados, QtQuick.Layouts, bindings declarativos e componentes reutilizáveis. Preserve teclado, foco, semântica e feedback. Leia references/qml-implementation.md. Para projeto novo, consulte assets/starter/ como referência funcional.
6. Complete os estados. Hover, pressed, focus, disabled, loading, empty, error, selected, scroll e feedback de ação. O modo claro, se exigido, precisa ser realmente legível. Use animações discretas e configuráveis; não anime todo elemento sem propósito.
7. Valide execução e aparência. Compile e rode se houver toolchain. Execute lint (qmllint) quando disponível e inspecione a UI em tamanhos desktop distintos. Se puder gerar screenshots, examine-as, corrija falhas e reporte o que realmente testou. Sem toolchain, faça validação estática e deixe explícito que não executou. Siga references/quality-gates.md.

Princípios visuais que devem aparecer no código

• Aparência de aplicação de trabalho, não de página web: navegação persistente, sidebar limpa, hierarquia de informação, ações previsíveis, áreas de rolagem apropriadas.
• Densidade controlada: boa quantidade de informação visível sem sacrificar respiro; tipografia legível, textos curtos, valores com destaque, dados secundários discretos.
• Superfícies coordenadas: fundo, sidebar, painéis, bordas discretas, acentos usados com parcimônia; evite sombras, gradientes e vidro excessivos.
• Design tokens semânticos e consistentes. Não espalhe códigos hexadecimais pelos arquivos de componentes.
• Layout adaptável a janelas redimensionáveis, DPI e textos longos. Utilize RowLayout, ColumnLayout, GridLayout, Layout.*, ScrollView, ListView/TableView conforme o caso.
• Motion cuidadoso: 120–220 ms para hover/seleção, ~180–280 ms para transições de áreas leves quando apropriado. Use Behavior/Transition com moderação. Evite efeitos que prejudiquem a fluidez.
• Ícones coesos: preferir SVGs locais licenciados e incorporados como recursos; não substituir iconografia por emoji. Se não houver ícones, use texto e geometria simples.
• Acessibilidade: contraste legível, navegação por teclado, foco visível, labels acessíveis, alvos confortáveis, suporte a configurações de movimento reduzido quando disponíveis.

Restrições técnicas importantes

• Não troque o backend Qt/C++/Python nem acrescente WebView ou HTML/CSS só para reproduzir o visual, a menos que seja pedido.
• Não personalize os estilos nativos de Windows/macOS. Para controles customizados, use QtQuick.Controls.Basic ou um estilo customizado construído sobre templates Qt Quick Controls. Não misture vários estilos de Controls no mesmo componente.
• Não crie uma titlebar frameless por padrão: ela exige implementação correta de drag, resize, maximize, menus e comportamento multiplataforma. Mantenha a moldura do SO, salvo solicitação.
• Não misture anchors para a geometria de um item que esteja sendo dimensionado/posicionado por Layout pai. Anchors são adequados dentro dos componentes.
• Não faça I/O pesado, timers frequentes ou computações caras no thread da UI; use backend/modelos. Prefira ListView/TableView a Repeater em listas extensas.
• Use as APIs disponíveis na versão instalada do Qt; não suponha módulos gráficos, fontes ou bibliotecas de ícones extras.
• Evite demo enganosa: ações visuais devem ter um efeito real ou ser descritas claramente como placeholders.

Entrega esperada

Para cada implementação, retorne: (1) o que mudou; (2) escolhas de design; (3) arquivos afetados; (4) como executar; (5) validações realmente feitas e pendências. Na revisão de UI, cite defeitos concretos (hierarquia, contraste, espaçamento, estados e performance) e proponha correções aplicáveis.

Material de referência — carregamento sob demanda

• references/design-language.md: tokens, composição, padrões desktop e estados.
• references/qml-implementation.md: arquitetura, QML/Qt, CMake/Python, anti-patterns e componentes.
• references/quality-gates.md: critérios de aceite, testes e revisão visual.
• assets/starter/: shell de dashboard desktop em Qt 6.5+ + CMake + Qt Quick Controls Basic, com temas claro/escuro e componentes prontos para adaptação. Não copie o domínio ou layout do starter automaticamente.

Comandos úteis de verificação

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
# qmlformat / qmllint: execute se estiverem instalados e configurados no projeto

Fontes técnicas: https://doc.qt.io/qt-6/qtquick-bestpractices.html ; https://doc.qt.io/qt-6/qtquickcontrols-customize.html ; https://doc.qt.io/qt-6/qtquick-performance.html ; https://doc.qt.io/qt-6/qml-singleton.html