Skip to main content

StylingGuide

Styling Guide​

This guide explains how to customize the visual appearance of your PyQt/PySide app using the built-in theming engine powered by QCustomTheme, QSS (Qt Style Sheets), and dynamic SCSS variables.

Overview​

Styling in your Custom Widgets framework is:

  • Modular (.scss based)
  • Theme-aware (_variables.scss)
  • Auto-compiled (main.scss → .qss)
  • Designer and developer-friendly

Styling Structure​

Your project uses the following style-related files:

/Qss/
├── scss/
│   ├── _variables.scss     # Auto-generated theme variables (DO NOT EDIT)
│   ├── _styles.scss        # Core widget styling (read-only)
│ ├── defaultStyle.scss # Your app's custom overrides
│   └── main.scss           # SCSS entry point
├── icons/                  # Auto-generated icons for each theme color
├── fonts/                  # Optional custom fonts (e.g., Rosario)

How It Works​

  1. A theme is selected via QSettings or a widget like QCustomThemeList.
  2. The app reads variables from your JSON theme definition (colors, radius, etc.).
  3. These are written to _variables.scss.
  4. main.scss compiles to a .qss file using qtsass.
  5. Styles are applied to the running app.

Theme Variables (_variables.scss)​

Variables like the following are auto-injected based on your JSON CustomTheme:

$COLOR_BACKGROUND_1: #16191d;
$COLOR_TEXT_1: #ffffff;
$COLOR_ACCENT_1: #03C3C3;

$CARD_RADIUS: 12px;
$FOOTER_BG: #0f0f0f;

Note: Do not manually edit _variables.scss. Instead, define new variables in your theme JSON under "Other-variables".

defaultStyle.scss – Your Playground​

This is the file where you write your own styles.

// Sample override
QFrame#card {
  background-color: $COLOR_BACKGROUND_2;
  border-radius: $CARD_RADIUS;
}

You can reference any variable from _variables.scss in here.

Yes Styling Best Practices​

GoalDo this...
Change base background colorUpdate Background-color in your JSON theme
Add a border radiusUse $CARD_RADIUS in defaultStyle.scss
Make widget styles consistentUse SCSS variables instead of hardcoded HEX or px
Test a new theme quicklyModify the theme in JSON and relaunch or call update manually
Prevent re-stylingUse objectName (e.g., QPushButton#myBtn) for specificity

Live Testing Tips​

You can force recompile and apply styles manually:

from Custom_Widgets.QCustomTheme import QCustomTheme
theme = QCustomTheme()
theme.applyCompiledSass()

Or refresh styles with:

from Custom_Widgets.QAppSettings import QAppSettings
QAppSettings.updateAppSettings(self)

Icon Styling (Optional)​

Icons are automatically recolored using the theme’s Icons-color or Accent-color. You can override them in your QSS using styles like:

QPushButton#refreshBtn {
  qproperty-icon: url(':/icons/03C3C3/refresh.png');
}

Need More?​

Refer to the following: