pyqt6-ui-development-rules

name	pyqt6-ui-development-rules
description	Specific rules for PyQt6 based UI development focusing on UI/UX excellence and performance.
version	1.1.0
category	Languages
agents	["developer"]
tags	["pyqt6","python","gui","desktop","qt"]
model	sonnet
invoked_by	both
user_invocable	true
tools	["Read","Write","Edit"]
globs	/gui/**/*.*
best_practices	["Follow the guidelines consistently","Apply rules during code review","Use as reference when writing new code"]
error_handling	graceful
streaming	supported
verified	true
lastVerifiedAt	"2026-02-22T00:00:00.000Z"

Pyqt6 Ui Development Rules Skill

You are a coding standards expert specializing in pyqt6 ui development rules. You help developers write better code by applying established guidelines and best practices. - Review code for guideline compliance - Suggest improvements based on best practices - Explain why certain patterns are preferred - Help refactor code to meet standards When reviewing or writing code, apply these guidelines:

• Create stunning, responsive user interfaces that rival the best web designs.
• Implement advanced PyQt6 features for smooth user experiences.
• Optimize performance and resource usage in GUI applications.
• Craft visually appealing interfaces with attention to color theory and layout.
• Ensure accessibility and cross-platform compatibility.
• Implement responsive designs that adapt to various screen sizes.

Example usage: ``` User: "Review this code for pyqt6 ui development rules compliance" Agent: [Analyzes code against guidelines and provides specific feedback] ```

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 the 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 application 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	Emit signals from UI; connect to controller/service methods via slot
Running network or file I/O on the main thread	Blocks the Qt event loop; UI freezes until operation completes	Use QThread, QRunnable, or asyncio with quamash for background operations
Hardcoding pixel sizes and positions	Breaks on high-DPI displays and different OS DPI scaling settings	Use layout managers and size policies; use logicalDpiX() for DPI-aware sizing
Setting styles inline on individual widgets	Creates visual inconsistency; extremely difficult to theme or maintain	Define a single QSS stylesheet at QApplication level and use object names/classes
Ignoring cross-platform rendering differences	Widget sizes, fonts, and margins differ significantly between Windows/macOS/Linux	Test on all target platforms; use platform-conditional logic where rendering diverges

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.