Skip to content

QSS style guide

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

🎨 Theme previews

The three built-in themes ship with a color palette preview. Select a theme in the settings panel at runtime, or set settings_panel.theme.default in bin/config/app.config.yaml.

Blue Gray

Blue Gray - Dark
surface_sunken
22 26 32
surface_base
27 31 39
surface_raised
33 37 46
surface_overlay
44 51 64
surface_floating
52 59 74
border_subtle
54 61 76
accent_brand
#96CD32
text_primary
218 220 228
text_secondary
122 134 158
text_on_accent
255 255 255
semantic_success
#4ade80
semantic_warning
#fbbf24
semantic_error
#f87171
semantic_info
#60a5fa
Blue Gray - Light
surface_sunken
228 232 240
surface_base
240 243 249
surface_raised
255 255 255
surface_overlay
234 237 245
surface_floating
255 255 255
border_subtle
210 215 228
accent_brand
#96CD32
text_primary
28 32 40
text_secondary
90 100 122
text_on_accent
28 32 40
semantic_success
#16a34a
semantic_warning
#d97706
semantic_error
#dc2626
semantic_info
#2563eb

GitHub Dark

Github Dark — Dark
surface_sunken
#010409
surface_base
#0d1117
surface_raised
#161b22
surface_overlay
#21262d
surface_floating
#30363d
border_subtle
#30363d
accent_brand
#58a6ff
text_primary
#e6edf3
text_secondary
#8b949e
text_on_accent
#0d1117
semantic_success
#3fb950
semantic_warning
#d29922
semantic_error
#f85149
semantic_info
#58a6ff
Github Dark — Light
surface_sunken
#d0d7de
surface_base
#f6f8fa
surface_raised
#ffffff
surface_overlay
#eaeff2
surface_floating
#ffffff
border_subtle
#d0d7de
accent_brand
#0969da
text_primary
#1f2328
text_secondary
#656d76
text_on_accent
#ffffff
semantic_success
#1a7f37
semantic_warning
#9a6700
semantic_error
#cf222e
semantic_info
#0969da

Warm Dark

Warm Dark - Dark
surface_sunken
16 12 10
surface_base
24 20 16
surface_raised
33 28 22
surface_overlay
44 38 30
surface_floating
56 48 38
border_subtle
66 57 45
accent_brand
#d97706
text_primary
232 221 208
text_secondary
160 144 124
text_on_accent
24 20 16
semantic_success
#4ade80
semantic_warning
#fbbf24
semantic_error
#f87171
semantic_info
#7dd3fc
Warm Dark - Light
surface_sunken
218 210 196
surface_base
238 232 220
surface_raised
255 250 242
surface_overlay
230 223 210
surface_floating
255 250 242
border_subtle
206 196 180
accent_brand
#b45309
text_primary
30 24 16
text_secondary
100 86 66
text_on_accent
255 250 242
semantic_success
#15803d
semantic_warning
#92400e
semantic_error
#b91c1c
semantic_info
#0369a1

🏗️ 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;
}

✅ Best practices

  • Keep theme tokens centralized in config/theme files.
  • Avoid hardcoding colors in widget code when possible.
  • Prefer object names for targeted QSS rules.
  • 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
  • Qt resources pipeline — how themes are compiled and loaded