QSS Style Guide¶

This document defines practical QSS style conventions for EzQt App components.

General Principles¶

Use consistent colors, spacing, and borders across all core containers.
Prefer specific object names (#settings_panel, #menu_container, etc.).
Centralize palette values in theme/config files whenever possible.

Where Styles Come From¶

All .qss files found in bin/themes/ are loaded automatically at application startup in alphabetical order. The directory ships with three files:

File	Scope
`bin/themes/application.qss`	Application-level styles (window chrome, layout containers)
`bin/themes/extended.qss`	EzQt extended widgets (`OptionSelector`, `ThemeIcon`, etc.)
`bin/themes/global.qss`	Standard Qt widgets (`QPushButton`, `QLineEdit`, etc.)

To add project-specific styles, place an additional .qss file in the same directory. It will be picked up automatically on the next run.

Additional sources:

Resource defaults bundled in the package
Runtime application orchestrated by ThemeService

Core Containers¶

Main Window¶

QMainWindow {
  background: #20242b;
  color: #e7ecf3;
}

Settings Panel¶

QFrame#settings_panel {
  border-left: 1px solid #2f3640;
  background: #262b33;
}

QFrame#menu_container {
  background: #1d222a;
  border-right: 1px solid #2f3640;
}

Interactive Controls¶

Hover/Focus Baseline¶

QPushButton:hover,
QToolButton:hover {
  border-color: #4c5a6f;
}

QPushButton:focus,
QLineEdit:focus {
  border-color: #3b82f6;
}

Theme Selector Pattern¶

[type="OptionSelector_Selector"] {
  background: #3b82f6;
  border-radius: 6px;
}

Settings Button Open State¶

The settings button in the header receives a dynamic open property whose value is "true" when the settings panel is visible and "false" when it is hidden. Use this to give the button a distinct active appearance:

QPushButton#settings_btn[open="true"] {
  background: var(--accent_brand);
  border-color: var(--accent_brand);
}

QPushButton#settings_btn[open="false"] {
  background: transparent;
}

Practical Recommendations¶

Keep theme tokens centralized in config/theme files.
Avoid hardcoding colors in widget code when possible.
Prefer object names for targeted QSS rules.

Best Practices¶

Keep dark/light variants symmetrical when possible.
Validate styles on both Windows and Linux runtimes.
Keep transitions/animations meaningful and unobtrusive.

src/ezqt_app/services/ui/theme_service.py
src/ezqt_app/widgets/core/settings_panel.py