pyqt6-ui-development-rules

name	pyqt6-ui-development-rules
description	PyQt6 desktop GUI development rules -- signal/slot architecture, QSS theming, QThread concurrency, layout management, and cross-platform rendering. Enforces MVC separation and responsive UI patterns.
version	2.0.0
category	Languages
agents	["python-pro","developer"]
tags	["pyqt6","python","gui","desktop","qt","ui","signals-slots","qss","qthread"]
model	sonnet
invoked_by	both
user_invocable	true
tools	["Read","Write","Edit","Bash","Glob","Grep"]
globs	["**/gui/**/*.*","**/*_ui.py","**/*_dialog.py","**/*_window.py"]
best_practices	["Use Qt signal/slot mechanism for all UI-to-logic communication","Never block the main thread with long-running operations","Apply QSS stylesheets at the QApplication level for consistent theming","Use layout managers instead of absolute pixel coordinates","Test on all target platforms before release"]
error_handling	graceful
streaming	supported
verified	true
lastVerifiedAt	2026-03-01
source	builtin
trust_score	100
provenance_sha	aab9454f75a64219

PyQt6 UI Development Rules Skill

PyQt6 desktop GUI development specialist enforcing MVC separation, signal/slot architecture, QSS theming, threaded concurrency, and cross-platform rendering best practices. Ensures responsive, accessible, and visually consistent desktop applications. - Design MVC-separated PyQt6 application architecture - Implement signal/slot communication patterns between UI and business logic - Configure QSS application-level theming with dark/light mode support - Manage background operations with QThread, QRunnable, and QThreadPool - Build responsive layouts using QVBoxLayout, QHBoxLayout, QGridLayout, and QFormLayout - Implement custom QWidget subclasses with proper paintEvent handling - Set up cross-platform DPI-aware rendering - Configure accessibility features (screen reader support, keyboard navigation)

Overview

This skill enforces rules for building production-quality PyQt6 desktop applications. The core principles are: strict MVC separation via signals/slots, never blocking the UI thread, centralized theming via QSS, and layout-manager-driven responsive design. These rules prevent the most common PyQt6 failures: frozen UIs, untestable coupling, and platform-specific rendering bugs.

When to Use

• When building new PyQt6 desktop applications
• When refactoring existing PyQt/PySide code to PyQt6
• When debugging frozen or unresponsive Qt UIs
• When implementing custom widgets or complex layouts
• When setting up cross-platform desktop application builds

Iron Laws

1. ALWAYS use Qt's signal/slot mechanism for UI-to-logic communication -- direct method calls between UI and business logic layers break MVC separation and cause untestable coupling.
2. NEVER perform long-running operations on the main UI thread -- blocking the Qt event loop makes the interface unresponsive and triggers OS "not responding" dialogs.
3. ALWAYS apply QSS stylesheets at the QApplication level rather than per-widget -- per-widget inline styles create inconsistent themes and unmaintainable styling sprawl.
4. NEVER use absolute pixel coordinates for widget layout -- use Qt layout managers (QVBoxLayout, QHBoxLayout, QGridLayout) to ensure DPI-aware and cross-platform rendering.
5. ALWAYS test the UI on all target platforms before release -- PyQt6 rendering, font scaling, and widget sizing differ between Windows, macOS, and Linux.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Calling business logic directly from UI slots	Couples UI to logic; makes testing impossible and breaks MVC architecture