- 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.
Iron Laws
- 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.
- 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.
- ALWAYS apply QSS stylesheets at the application level rather than per-widget — per-widget inline styles create inconsistent themes and unmaintainable styling sprawl.
- NEVER use absolute pixel coordinates for widget layout — use Qt layout managers (QVBoxLayout, QHBoxLayout, QGridLayout) to ensure DPI-aware and cross-platform rendering.
- 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.