Communitygithub.com

pyside6-ui

Habilidade universal de arquitetura e design de UI/UX para PySide6 / Qt for Python, adequada para qualquer aplicativo desktop. Utilize sempre ao projetar, construir, refatorar, estilizar ou revisar janelas PySide6, shells de navegação, temas QSS, dashboards, tabelas de dados, barras de busca/filtro, formulários CRUD, diálogos modais, responsividade assíncrona, RTL/i18n ou fluxos de teclado.

O que é pyside6-ui?

Esta habilidade especializada fornece uma estrutura completa para projetar e construir interfaces de desktop limpas, responsivas e centradas no ser humano usando PySide6 (Qt for Python). Ela é projetada para ser universal, adaptando-se a qualquer domínio de aplicativo, e enfatiza a integração com temas e convenções existentes do projeto, em vez de sobrescrevê-los. A habilidade está estruturada em seções de consulta sob demanda, cobrindo desde design system e QSS até arquitetura de navegação, tabelas de dados, formulários, diálogos e acessibilidade. Inclui leis de UX universais aplicadas a interfaces desktop, um conjunto de tokens de design system padrão (com opções claras e de alto contraste) e regras de engenharia não negociáveis do PySide6, como uso de Model/View para dados tabulares, layouts responsivos e validação inline. Um portão de qualidade pré-voo é fornecido para verificar a implementação antes da finalização. A habilidade suporta qualquer aplicação desktop PySide6 e funciona com ferramentas de agente de IA como Claude Code, Cursor, Codex e similares, fornecendo orientação detalhada e referências para cada aspecto da construção da interface do usuário.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedBoure/skills/tree/main/pyside6-ui

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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)

  1. Lei de Jakob: Corresponda às convenções estabelecidas de desktop (Ctrl+S salvar, Ctrl+F buscar, Esc cancelar/limpar, F5 atualizar, posicionamento padrão de menu/barra de ferramentas) para que os usuários se sintam imediatamente fluentes.
  2. Lei de Fitts: Mantenha as ações primárias grandes o suficiente (>= 36px de altura, >= 42px para 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.
  3. 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.
  4. Lei de Miller & Proximidade Gestáltica: Agrupe controles relacionados em grupos visuais limpos (CardFrame) com espaçamento consistente (8px dentro de um grupo, 16px–24px entre grupos) para que os usuários examinem a estrutura sem esforço.
  5. Limiar de Doherty (< 400ms de 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.
  6. 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 solid na cor de destaque primária em todos os inputs e botões interativos.
  • 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)
  • 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 20px Negrito, Título de Seção 15px SemiNegrito, Corpo/Célula 13px Regular, Rótulo/Legenda 12px Médio, Métrica Hero 22px–26px Negrito.
  • 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)
  • 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/Toque 42px+, Cabeçalho de Tabela 38px, Linha de Tabela >= 42px.
    • Raios de Borda: Controles 6px, Cartões/Painéis 10px, Modais 12px, Pílulas de Status 11px.

4. Regras de Engenharia PySide6 Não Negociáveis

  1. Adapte-se ao Código Existente Primeiro: Reutilize constantes de tema, widgets base e ajudantes existentes antes de introduzir novas abstrações.
  2. Agrupamento Espacial Limpo: Use cartões QFrame (borda fina 1px, contraste de superfície sutil) ou painéis QSplitter em vez de bordas pesadas de QGroupBox aninhadas.
  3. Model/View para Dados Tabulares e em Árvore: Use QTableView / QTreeView com QAbstractItemModel (QAbstractTableModel), QSortFilterProxyModel e QStyledItemDelegate. Evite preencher células de QTableWidget com widgets aninhados pesados.
  4. QSS Semântico em Vez de Spaghetti Inline: Estilize via funções setObjectName(...) (PrimaryButton, DangerButton, Card, PageTitle) e propriedades dinâmicas ([invalid="true"] com unpolish()/polish()) em vez de espalhar strings setStyleSheet(...) brutas.
  5. Layouts Responsivos (Tamanhos de Contêiner Zero Fixos): Nunca chame setFixedSize() em janelas, cartões ou tabelas. Confie em layouts, fatores de estiramento, QSizePolicy e QScrollArea para que as UIs sejam dimensionadas de forma limpa em diferentes resoluções, displays HiDPI e comprimentos de texto traduzido.
  6. Explique Estados Desabilitados e Valide Inline: Toda chamada de setEnabled(False) DEVE incluir setToolTip(...) explicando por que está desabilitado. Valide entradas inline com rótulos de erro auxiliares — nunca interrompa a digitação com QMessageBox.
  7. 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.
  8. Foco no Teclado e Feedback Não Bloqueante: Defina o foco inicial em showEvent(), configure setTabOrder(), suporte Enter/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.
  9. 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 sutil 7px + 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 de QStyledItemDelegate.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 (PageHeader ou 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 QStackedWidget em 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?

Habilidades Relacionadas