Universal PySide6 UI/UX Architecture Skill
Design and build clean, responsive, human-centered desktop interfaces in PySide6 for any application domain. Always inspect the target project's existing theme, widgets, and conventions first—integrate naturally with them rather than overwriting existing abstractions. Load only the specific reference file(s) needed for the current task.
1. Progressive Disclosure Routing (Read On Demand)
- Theming, QSS stylesheets, Light/Dark mode, HiDPI, or layout primitives → Read
./references/design-system-and-qss.md - Main window architecture, sidebars, tabs, docks, splitters, or dashboards → Read
./references/navigation-and-shell.md - Data tables, lists, trees, search bars, filters, or empty/loading states → Read
./references/data-tables-and-filters.md - Modal dialogs (
QDialog), forms, detail drawers, validation, or toast/progress feedback → Read./references/forms-dialogs-and-feedback.md - Keyboard shortcuts, accessibility, i18n/RTL layouts, or background threading → Read
./references/accessibility-i18n-and-async.md - Bootstrapping a brand-new PySide6 app with no existing theme → Optionally reference
./assets/base-theme.qss
2. Universal UX Laws (Applied to Desktop UI)
- Jakob's Law: Match established desktop conventions (
Ctrl+Ssave,Ctrl+Fsearch,Esccancel/clear,F5refresh, standard menu/toolbar placement) so users feel immediately fluent. - Fitts's Law: Keep primary actions large enough (
>= 36pxheight,>= 42pxfor touch/high-frequency workflows) and anchored near where the user's attention already is; avoid forcing long mouse travel for repeated actions. - Hick's Law & Progressive Disclosure: Limit visible choices at any moment. Group secondary options into drawers, tabs, or overflow menus instead of crowding every control onto one screen.
- Miller's Law & Gestalt Proximity: Chunk related controls into clean visual groups (
CardFrame) with consistent spacing (8pxwithin a group,16px–24pxbetween groups) so users scan structure effortlessly. - Doherty Threshold (
< 400msPerceived Response): Never freeze the Qt event loop. Run I/O, network, and heavy computation off the main thread (QThreadPool/QRunnable) and show immediate loading or progress feedback. - Error Prevention & Safe Recovery: Validate inline before submission, disable impossible actions with clear tooltips explaining why, and require explicit confirmation only for destructive or irreversible operations.
3. Default Design System Tokens (Adaptable)
If the project already defines a palette, typography, or spacing system, follow the project's tokens. Otherwise, use these clean, high-contrast defaults:
- Accent & Focus:
- Primary Accent:
#0F766E(Hover:#0D5F59, Pressed:#0A4A45, Soft Tint:#CCFBF1/#F0FDFA) — or adapt to the app's brand hue. - Focus Ring:
2px solidprimary accent on all interactive inputs and buttons.
- Primary Accent:
- Neutral Surface Hierarchy (Light / Dark):
- App Canvas:
#F8FAFC(Light) /#0F172A(Dark) - Elevated Surface / Card:
#FFFFFF(Light) /#1E293B(Dark) - Subtle Secondary Surface (Headers, Footers, Zebra):
#F1F5F9(Light) /#334155(Dark) - Hairline Border / Divider:
#E2E8F0(Light) /#334155(Dark) - Default Input Border:
#CBD5E1(Light) /#475569(Dark)
- App Canvas:
- Typography & Ink Hierarchy:
- Primary Text:
#0F172A(Light) /#F8FAFC(Dark) - Secondary / Label Text:
#475569(Light) /#CBD5E1(Dark) - Muted / Disabled Text:
#94A3B8(Light) /#64748B(Dark) - Font Stack:
"Segoe UI", "Inter", "Cairo", system-ui, sans-serif(cleanly supports Latin, Arabic, and multilingual UIs). - Type Scale: Page Title
20pxBold, Section Title15pxSemiBold, Body/Cell13pxRegular, Label/Caption12pxMedium, Hero Metric22px–26pxBold.
- Primary Text:
- Semantic Status Tokens:
- Success: Text
#15803D, Fill#DCFCE7(Dark:#4ADE80/#14532D) - Warning: Text
#B45309, Fill#FEF3C7(Dark:#FBBF24/#451A03) - Danger: Text
#B91C1C, Fill#FEE2E2(Dark:#F87171/#450A0A) - Info: Text
#0369A1, Fill#E0F2FE(Dark:#38BDF8/#0C4A6E)
- Success: Text
- Spacing & Geometry:
- Spacing Scale:
4px(tight),8px(related elements),12px(toolbar/form gap),16px(card padding),20px–24px(page margins). - Control Heights: Standard Inputs/Buttons
36px, High-Frequency/Touch Controls42px+, Table Header38px, Table Row>= 42px. - Border Radii: Controls
6px, Cards/Panels10px, Modals12px, Status Pills11px.
- Spacing Scale:
4. Non-Negotiable PySide6 Engineering Rules
- Adapt to Existing Codebase First: Reuse existing theme constants, base widgets, and helpers before introducing new abstractions.
- Clean Spatial Grouping: Use
QFramecards (1pxhairline border, subtle surface contrast) orQSplitterpanes instead of heavy nestedQGroupBoxborders. - Model/View for Tabular & Tree Data: Use
QTableView/QTreeViewwithQAbstractItemModel(QAbstractTableModel),QSortFilterProxyModel, andQStyledItemDelegate. Avoid populatingQTableWidgetcells with heavy nested widgets. - Semantic QSS Over Inline Spaghetti: Style via
setObjectName(...)roles (PrimaryButton,DangerButton,Card,PageTitle) and dynamic properties ([invalid="true"]withunpolish()/polish()) rather than scattering rawsetStyleSheet(...)strings. - Responsive Layouts (Zero Fixed Container Sizes): Never call
setFixedSize()on windows, cards, or tables. Rely on layouts, stretch factors,QSizePolicy, andQScrollAreaso UIs scale cleanly across resolutions, HiDPI displays, and translated text lengths. - Explain Disabled States & Validate Inline: Every
setEnabled(False)call MUST includesetToolTip(...)explaining why it is disabled. Validate inputs inline with helper error labels—never interrupt typing withQMessageBox. - One Canonical Location Per Action: Never duplicate the same action in both a top bar and a bottom footer. Place primary page CTAs top-right in
PageHeader, and primary form/dialog CTAs bottom-right in the modal footer. - Keyboard-First & Non-Blocking Feedback: Set initial focus in
showEvent(), wiresetTabOrder(), supportEnter/Esc, and use non-blocking overlay toasts or status bars for routine confirmations—reserving modal dialogs for destructive confirmations. - Restrained, Content-Fitted Status Badges: Never stretch table status pills to a wide uniform fixed width or flood every healthy row with heavy saturated badges. Fit pill width dynamically to
QFontMetrics.horizontalAdvance(text) + padding, keep routine healthy states visually quiet (e.g., subtle7pxstatus dot + crisp text) so warnings/errors pop immediately, and preserve row selection and bottom hairline dividers inside customQStyledItemDelegate.paint()overrides.
5. Pre-Flight Quality Gate
Before finalizing any PySide6 UI implementation, verify:
- Does every view have clear visual hierarchy (
PageHeaderor structured workspace bar) with no orphaned floating controls? - Do all interactive controls share uniform heights (
>= 36px), clear hover/focus states, and sufficient color contrast? - Are numeric/tabular columns right-aligned and formatted according to the app's locale?
- Are table status badges sized to their text, visually calm on healthy rows, and aligned seamlessly with row selection and dividers?
- Do empty, zero-match, and loading states use a dedicated
QStackedWidgetstate instead of blank whitespace? - Does every disabled control explain itself via
setToolTip()? - Are long-running tasks offloaded from the UI thread so the window never freezes?