Habilidade Universal de Arquitetura UI/UX PySide6
Projete e construa interfaces de desktop limpas, responsivas e centradas no ser humano em PySide6 para qualquer domínio de aplicativo. Sempre inspecione primeiro o tema, widgets e convenções existentes do projeto-alvo — integre-se naturalmente a eles, em vez de sobrescrever abstrações existentes. Carregue apenas o(s) arquivo(s) de referência específico(s) necessário(s) para a tarefa atual.
1. Roteamento de Divulgação Progressiva (Leitura Sob Demanda)
- Temas, folhas de estilo QSS, modo Claro/Escuro, HiDPI ou primitivas de layout → Leia
./references/design-system-and-qss.md - Arquitetura de janela principal, barras laterais, abas, docks, divisores ou dashboards → Leia
./references/navigation-and-shell.md - Tabelas de dados, listas, árvores, barras de busca, filtros ou estados vazio/carregamento → Leia
./references/data-tables-and-filters.md - Diálogos modais (
QDialog), formulários, gavetas de detalhes, validação ou feedback de toast/progresso → Leia./references/forms-dialogs-and-feedback.md - Atalhos de teclado, acessibilidade, layouts i18n/RTL ou threading em segundo plano → Leia
./references/accessibility-i18n-and-async.md - Inicialização de um novo aplicativo PySide6 sem tema existente → Opcionalmente, consulte
./assets/base-theme.qss
2. Leis Universais de UX (Aplicadas à Interface Desktop)
- Lei de Jakob: Corresponda às convenções estabelecidas de desktop (
Ctrl+Ssalvar,Ctrl+Fbuscar,Esccancelar/limpar,F5atualizar, posicionamento padrão de menu/barra de ferramentas) para que os usuários se sintam imediatamente fluentes. - Lei de Fitts: Mantenha as ações primárias grandes o suficiente (
>= 36pxde altura,>= 42pxpara toque/fluxos de alta frequência) e ancoradas perto de onde a atenção do usuário já está; evite forçar longos movimentos do mouse para ações repetidas. - Lei de Hick & Divulgação Progressiva: Limite as escolhas visíveis a qualquer momento. Agrupe opções secundárias em gavetas, abas ou menus de estouro, em vez de sobrecarregar cada controle em uma única tela.
- Lei de Miller & Proximidade Gestáltica: Agrupe controles relacionados em grupos visuais limpos (
CardFrame) com espaçamento consistente (8pxdentro de um grupo,16px–24pxentre grupos) para que os usuários examinem a estrutura sem esforço. - Limiar de Doherty (
< 400msde Resposta Percebida): Nunca congele o loop de eventos do Qt. Execute E/S, rede e computação pesada fora da thread principal (QThreadPool/QRunnable) e mostre feedback imediato de carregamento ou progresso. - Prevenção de Erros e Recuperação Segura: Valide inline antes do envio, desabilite ações impossíveis com dicas de ferramenta claras explicando o motivo, e exija confirmação explícita apenas para operações destrutivas ou irreversíveis.
3. Tokens Padrão do Design System (Adaptáveis)
Se o projeto já definir uma paleta, tipografia ou sistema de espaçamento, siga os tokens do projeto. Caso contrário, use estes padrões limpos e de alto contraste:
- Cor de Destaque e Foco:
- Destaque Primário:
#0F766E(Hover:#0D5F59, Pressionado:#0A4A45, Tonalidade Suave:#CCFBF1/#F0FDFA) — ou adapte ao matiz da marca do aplicativo. - Anel de Foco:
2px solidna cor de destaque primária em todos os inputs e botões interativos.
- Destaque Primário:
- Hierarquia de Superfície Neutra (Claro / Escuro):
- Tela do Aplicativo:
#F8FAFC(Claro) /#0F172A(Escuro) - Superfície Elevada / Cartão:
#FFFFFF(Claro) /#1E293B(Escuro) - Superfície Secundária Sutil (Cabeçalhos, Rodapés, Zebra):
#F1F5F9(Claro) /#334155(Escuro) - Borda Fina / Divisor:
#E2E8F0(Claro) /#334155(Escuro) - Borda Padrão de Input:
#CBD5E1(Claro) /#475569(Escuro)
- Tela do Aplicativo:
- Hierarquia de Tipografia e Tinta:
- Texto Primário:
#0F172A(Claro) /#F8FAFC(Escuro) - Texto Secundário / Rótulo:
#475569(Claro) /#CBD5E1(Escuro) - Texto Silenciado / Desabilitado:
#94A3B8(Claro) /#64748B(Escuro) - Pilha de Fontes:
"Segoe UI", "Inter", "Cairo", system-ui, sans-serif(suporta limpidamente latim, árabe e UIs multilíngues). - Escala Tipográfica: Título de Página
20pxNegrito, Título de Seção15pxSemiNegrito, Corpo/Célula13pxRegular, Rótulo/Legenda12pxMédio, Métrica Hero22px–26pxNegrito.
- Texto Primário:
- Tokens de Status Semântico:
- Sucesso: Texto
#15803D, Preenchimento#DCFCE7(Escuro:#4ADE80/#14532D) - Aviso: Texto
#B45309, Preenchimento#FEF3C7(Escuro:#FBBF24/#451A03) - Perigo: Texto
#B91C1C, Preenchimento#FEE2E2(Escuro:#F87171/#450A0A) - Informação: Texto
#0369A1, Preenchimento#E0F2FE(Escuro:#38BDF8/#0C4A6E)
- Sucesso: Texto
- Espaçamento e Geometria:
- Escala de Espaçamento:
4px(apertado),8px(elementos relacionados),12px(espaço barra de ferramentas/formulário),16px(preenchimento do cartão),20px–24px(margens da página). - Alturas de Controle: Inputs/Botões Padrão
36px, Controles de Alta Frequência/Toque42px+, Cabeçalho de Tabela38px, Linha de Tabela>= 42px. - Raios de Borda: Controles
6px, Cartões/Painéis10px, Modais12px, Pílulas de Status11px.
- Escala de Espaçamento:
4. Regras de Engenharia PySide6 Não Negociáveis
- Adapte-se ao Código Existente Primeiro: Reutilize constantes de tema, widgets base e ajudantes existentes antes de introduzir novas abstrações.
- Agrupamento Espacial Limpo: Use cartões
QFrame(borda fina1px, contraste de superfície sutil) ou painéisQSplitterem vez de bordas pesadas deQGroupBoxaninhadas. - Model/View para Dados Tabulares e em Árvore: Use
QTableView/QTreeViewcomQAbstractItemModel(QAbstractTableModel),QSortFilterProxyModeleQStyledItemDelegate. Evite preencher células deQTableWidgetcom widgets aninhados pesados. - QSS Semântico em Vez de Spaghetti Inline: Estilize via funções
setObjectName(...)(PrimaryButton,DangerButton,Card,PageTitle) e propriedades dinâmicas ([invalid="true"]comunpolish()/polish()) em vez de espalhar stringssetStyleSheet(...)brutas. - Layouts Responsivos (Tamanhos de Contêiner Zero Fixos): Nunca chame
setFixedSize()em janelas, cartões ou tabelas. Confie em layouts, fatores de estiramento,QSizePolicyeQScrollAreapara que as UIs sejam dimensionadas de forma limpa em diferentes resoluções, displays HiDPI e comprimentos de texto traduzido. - Explique Estados Desabilitados e Valide Inline: Toda chamada de
setEnabled(False)DEVE incluirsetToolTip(...)explicando por que está desabilitado. Valide entradas inline com rótulos de erro auxiliares — nunca interrompa a digitação comQMessageBox. - Um Local Canônico por Ação: Nunca duplique a mesma ação em uma barra superior e um rodapé inferior. Coloque CTAs primários da página no canto superior direito em
PageHeader, e CTAs primários de formulário/diálogo no canto inferior direito no rodapé do modal. - Foco no Teclado e Feedback Não Bloqueante: Defina o foco inicial em
showEvent(), configuresetTabOrder(), suporteEnter/Esc, e use toasts ou barras de status sobrepostas não bloqueantes para confirmações de rotina — reservando diálogos modais para confirmações destrutivas. - Emblemas de Status Contidos e Ajustados ao Conteúdo: Nunca estique pílulas de status de tabela para uma largura fixa uniforme ou inunde cada linha saudável com emblemas saturados pesados. Ajuste a largura da pílula dinamicamente para
QFontMetrics.horizontalAdvance(text) + padding, mantenha estados saudáveis de rotina visualmente discretos (por exemplo, ponto de status sutil7px+ texto nítido) para que avisos/erros apareçam imediatamente, e preserve a seleção de linha e divisores de borda inferior dentro de sobrescritas personalizadas deQStyledItemDelegate.paint().
5. Portão de Qualidade Pré-Voo
Antes de finalizar qualquer implementação de UI PySide6, verifique:
- Cada vista tem uma hierarquia visual clara (
PageHeaderou barra de espaço de trabalho estruturada) sem controles flutuantes órfãos? - Todos os controles interativos compartilham alturas uniformes (
>= 36px), estados claros de hover/foco e contraste de cor suficiente? - As colunas numéricas/tabulares estão alinhadas à direita e formatadas de acordo com a localidade do aplicativo?
- Os emblemas de status da tabela são dimensionados para o texto, visualmente calmos em linhas saudáveis e alinhados perfeitamente com a seleção de linha e divisores?
- Os estados vazio, sem correspondência e carregamento usam um estado dedicado do
QStackedWidgetem vez de espaço em branco? - Cada controle desabilitado explica a si mesmo via
setToolTip()? - As tarefas de longa duração são descarregadas da thread da UI para que a janela nunca congele?