Communitygithub.com

pyside6-ui

Compétence universelle d'architecture et de design UI/UX pour toute application de bureau utilisant PySide6/Qt for Python. À utiliser lors de la conception, construction, refonte, stylisation ou révision de fenêtres PySide6, coques de navigation, thèmes QSS, tableaux de bord, tables de données, barres de recherche/filtre, formulaires CRUD, boîtes de dialogue modales, réactivité asynchrone, RTL/i18n ou workflows clavier.

Qu'est-ce que pyside6-ui ?

Cette compétence fournit un système complet d'architecture UI/UX pour les applications de bureau basées sur PySide6 (Qt for Python). Elle est conçue pour être universelle : au lieu d'imposer une seule approche, elle s'adapte d'abord au thème, aux widgets et aux conventions existants du projet cible. Elle applique des lois UX éprouvées — loi de Jakob, loi de Fitts, loi de Hick, loi de Miller et seuil de Doherty — à l'interface de bureau, garantissant une expérience utilisateur cohérente, réactive et centrée sur l'humain. La compétence propose un système de design modulaire avec des jetons de thème (palette de couleurs, typographie, espacement, états sémantiques) qui peuvent être facilement remplacés par ceux du projet. Elle impose également des règles d'ingénierie PySide6 non-négociables : utilisation du modèle/vue pour les données tabulaires, styles QSS sémantiques, mises en page responsives sans tailles fixes, validation en ligne, navigation clavier complète et gestion de l'accessibilité/i18n/RTL. La compétence utilise un routage de lecture à la demande : elle charge uniquement les fichiers de référence spécifiques (par exemple, système de design et QSS, navigation et coque, tables de données et filtres, formulaires et dialogues, accessibilité et asynchrone) nécessaires à la tâche en cours. Elle est compatible avec tout éditeur ou agent prenant en charge l'architecture basée sur les compétences, comme Claude Code, Cursor, ou Codex.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Compétence universelle d'architecture UI/UX PySide6

Concevez et construisez des interfaces de bureau propres, réactives et centrées sur l'humain dans PySide6 pour tout domaine d'application. Inspectez toujours d'abord le thème, les widgets et les conventions existants du projet cible — intégrez-vous naturellement à eux plutôt que de remplacer les abstractions existantes. Chargez uniquement le(s) fichier(s) de référence spécifique(s) nécessaire(s) à la tâche en cours.

1. Routage par divulgation progressive (lecture à la demande)

  • Thématisation, feuilles de style QSS, mode Clair/Sombre, HiDPI ou primitives de mise en page → Lire ./references/design-system-and-qss.md
  • Architecture de fenêtre principale, barres latérales, onglets, volets, séparateurs ou tableaux de bord → Lire ./references/navigation-and-shell.md
  • Tables de données, listes, arbres, barres de recherche, filtres ou états vides/chargement → Lire ./references/data-tables-and-filters.md
  • Boîtes de dialogue modales (QDialog), formulaires, panneaux de détail, validation ou retour toast/progression → Lire ./references/forms-dialogs-and-feedback.md
  • Raccourcis clavier, accessibilité, mises en page i18n/RTL ou threads d'arrière-plan → Lire ./references/accessibility-i18n-and-async.md
  • Amorçage d'une toute nouvelle application PySide6 sans thème existant → Référence facultative ./assets/base-theme.qss

2. Lois UX universelles (appliquées à l'interface de bureau)

  1. Loi de Jakob : Respectez les conventions de bureau établies (Ctrl+S enregistrer, Ctrl+F rechercher, Esc annuler/effacer, F5 actualiser, placement standard des menus/barres d'outils) afin que les utilisateurs se sentent immédiatement à l'aise.
  2. Loi de Fitts : Gardez les actions principales suffisamment grandes (>= 36px de hauteur, >= 42px pour le tactile/les workflows à haute fréquence) et ancrées là où l'attention de l'utilisateur se trouve déjà ; évitez de forcer de longs déplacements de souris pour des actions répétées.
  3. Loi de Hick & Divulgation progressive : Limitez les choix visibles à tout moment. Regroupez les options secondaires dans des tiroirs, des onglets ou des menus débordants plutôt que d'encombrer chaque contrôle sur un seul écran.
  4. Loi de Miller & Proximité Gestalt : Regroupez les contrôles liés en groupes visuels propres (CardFrame) avec un espacement cohérent (8px au sein d'un groupe, 16px–24px entre les groupes) afin que les utilisateurs parcourent la structure sans effort.
  5. Seuil de Doherty (< 400ms de réponse perçue) : Ne bloquez jamais la boucle d'événements Qt. Exécutez les E/S, les opérations réseau et les calculs lourds hors du thread principal (QThreadPool / QRunnable) et affichez immédiatement un retour de chargement ou de progression.
  6. Prévention des erreurs et récupération sécurisée : Validez en ligne avant la soumission, désactivez les actions impossibles avec des info-bulles claires expliquant pourquoi, et exigez une confirmation explicite uniquement pour les opérations destructrices ou irréversibles.

3. Jetons de système de design par défaut (adaptables)

Si le projet définit déjà une palette, une typographie ou un système d'espacement, suivez les jetons du projet. Sinon, utilisez ces valeurs par défaut propres et à contraste élevé :

  • Accentuation & Focus :
    • Accentuation principale : #0F766E (Survol : #0D5F59, Enfoncé : #0A4A45, Teinte douce : #CCFBF1 / #F0FDFA) — ou adaptez à la teinte de la marque de l'application.
    • Anneau de focus : 2px solid de la couleur d'accentuation principale sur toutes les entrées et tous les boutons interactifs.
  • Hiérarchie de surface neutre (Clair / Sombre) :
    • Toile de l'application : #F8FAFC (Clair) / #0F172A (Sombre)
    • Surface surélevée / Carte : #FFFFFF (Clair) / #1E293B (Sombre)
    • Surface secondaire subtile (En-têtes, Pieds de page, Zébrures) : #F1F5F9 (Clair) / #334155 (Sombre)
    • Bordure fine / Séparateur : #E2E8F0 (Clair) / #334155 (Sombre)
    • Bordure d'entrée par défaut : #CBD5E1 (Clair) / #475569 (Sombre)
  • Typographie & Hiérarchie d'encre :
    • Texte principal : #0F172A (Clair) / #F8FAFC (Sombre)
    • Texte secondaire / d'étiquette : #475569 (Clair) / #CBD5E1 (Sombre)
    • Texte atténué / désactivé : #94A3B8 (Clair) / #64748B (Sombre)
    • Pile de polices : "Segoe UI", "Inter", "Cairo", system-ui, sans-serif (prend en charge proprement le latin, l'arabe et les IU multilingues).
    • Échelle typographique : Titre de page 20px Gras, Titre de section 15px Semi-gras, Corps/Cellule 13px Normal, Étiquette/Légende 12px Moyen, Métrique vedette 22px–26px Gras.
  • Jetons d'état sémantiques :
    • Succès : Texte #15803D, Remplissage #DCFCE7 (Sombre : #4ADE80 / #14532D)
    • Avertissement : Texte #B45309, Remplissage #FEF3C7 (Sombre : #FBBF24 / #451A03)
    • Danger : Texte #B91C1C, Remplissage #FEE2E2 (Sombre : #F87171 / #450A0A)
    • Info : Texte #0369A1, Remplissage #E0F2FE (Sombre : #38BDF8 / #0C4A6E)
  • Espacement & Géométrie :
    • Échelle d'espacement : 4px (serré), 8px (éléments liés), 12px (espacement barre d'outils/formulaire), 16px (rembourrage de carte), 20px–24px (marges de page).
    • Hauteurs des contrôles : Entrées/Boutons standard 36px, Contrôles à haute fréquence/Tactiles 42px+, En-tête de tableau 38px, Ligne de tableau >= 42px.
    • Rayons de bordure : Contrôles 6px, Cartes/Panneaux 10px, Modales 12px, Pastilles d'état 11px.

4. Règles d'ingénierie PySide6 non-négociables

  1. Adaptez-vous d'abord à la base de code existante : Réutilisez les constantes de thème, les widgets de base et les assistants existants avant d'introduire de nouvelles abstractions.
  2. Regroupement spatial propre : Utilisez des cartes QFrame (bordure fine 1px, contraste de surface subtil) ou des volets QSplitter plutôt que des bordures QGroupBox imbriquées lourdes.
  3. Modèle/Vue pour les données tabulaires et arborescentes : Utilisez QTableView / QTreeView avec QAbstractItemModel (QAbstractTableModel), QSortFilterProxyModel et QStyledItemDelegate. Évitez de peupler les cellules QTableWidget avec des widgets imbriqués lourds.
  4. QSS sémantique plutôt que spaghetti en ligne : Stylisez via les rôles setObjectName(...) (PrimaryButton, DangerButton, Card, PageTitle) et les propriétés dynamiques ([invalid="true"] avec unpolish()/polish()) plutôt que de disperser des chaînes setStyleSheet(...) brutes.
  5. Mises en page responsives (zéro taille de conteneur fixe) : N'appelez jamais setFixedSize() sur les fenêtres, les cartes ou les tables. Fiez-vous aux mises en page, aux facteurs d'étirement, à QSizePolicy et à QScrollArea pour que les IU s'adaptent proprement aux différentes résolutions, aux écrans HiDPI et aux longueurs de texte traduit.
  6. Expliquez les états désactivés et validez en ligne : Chaque appel setEnabled(False) DOIT inclure setToolTip(...) expliquant pourquoi il est désactivé. Validez les entrées en ligne avec des étiquettes d'erreur d'assistance — n'interrompez jamais la saisie avec QMessageBox.
  7. Un emplacement canonique par action : Ne dupliquez jamais la même action à la fois dans une barre supérieure et un pied de page inférieur. Placez les appels à l'action principaux de la page en haut à droite dans PageHeader, et les appels à l'action principaux du formulaire/dialogue en bas à droite dans le pied de page modal.
  8. Raccourcis clavier en priorité et retour non bloquant : Définissez le focus initial dans showEvent(), câblez setTabOrder(), prenez en charge Entrée/Échap, et utilisez des toasts superposés non bloquants ou des barres d'état pour les confirmations de routine — réservez les dialogues modaux pour les confirmations destructrices.
  9. Pastilles d'état sobres et ajustées au contenu : N'étirez jamais les pastilles d'état des tableaux sur une largeur fixe uniforme et n'inondez pas chaque ligne saine de badges saturés lourds. Ajustez dynamiquement la largeur des pastilles à l'aide de QFontMetrics.horizontalAdvance(text) + padding, maintenez les états sains de routine visuellement discrets (par exemple, un point d'état subtil 7px + texte net) afin que les avertissements/erreurs ressortent immédiatement, et conservez la sélection de ligne et les séparateurs fins inférieurs à l'intérieur des remplacements QStyledItemDelegate.paint() personnalisés.

5. Porte de qualité pré-vol

Avant de finaliser toute implémentation UI PySide6, vérifiez :

  • Chaque vue a-t-elle une hiérarchie visuelle claire (PageHeader ou barre d'espace de travail structurée) sans contrôles flottants orphelins ?
  • Tous les contrôles interactifs partagent-ils des hauteurs uniformes (>= 36px), des états de survol/focus clairs et un contraste de couleurs suffisant ?
  • Les colonnes numériques/tabulaires sont-elles alignées à droite et formatées selon la locale de l'application ?
  • Les pastilles d'état des tableaux sont-elles dimensionnées à leur texte, visuellement calmes sur les lignes saines et alignées de manière transparente avec la sélection de ligne et les séparateurs ?
  • Les états vides, sans correspondance et de chargement utilisent-ils un état dédié QStackedWidget au lieu d'un espace blanc vide ?
  • Chaque contrôle désactivé s'explique-t-il via setToolTip() ?
  • Les tâches de longue durée sont-elles déchargées du thread de l'interface utilisateur afin que la fenêtre ne gèle jamais ?

Skills associés