📘 Эта документация также доступна на русском
📋 Contents
- Overview
- Creating the Theme Folder
- Theme Variants
- Style File
- Style Inheritance
- Animation configuration
- Metadata
- Screenshots
- Fonts and Icons
📖 Overview
Themes in PortProtonQT allow customizing the UI appearance. Themes are stored under:
~/.local/share/PortProtonQT/themes.
📁 Creating the Theme Folder
mkdir -p ~/.local/share/PortProtonQT/themes/my_custom_theme
🌓 Theme Variants
The theme tab groups light and dark variants under one base theme name.
- Dark variant folder:
my_custom_theme - Light variant folder:
my_custom_theme-light
If both folders exist, the application shows a separate variant selector with Dark, Light, and Auto. If only one folder exists, the variant selector is hidden and the existing theme is used directly.
Auto is the default variant. It follows the system color scheme using the desktop portal first, then gsettings, and Qt color scheme detection as a fallback.
Both variants are regular themes and must contain their own styles.py. Use THEME_INHERITS if one variant should reuse missing style values from another theme.
🎨 Style File (styles.py)
Create a styles.py in the theme root. It should define variables or functions that return QSS (Qt Style Sheets). For better organization, you can split your theme into multiple submodules by creating a subdirectory (e.g., styles, components, etc.) with separate Python files for different components, and import them in styles.py.
Example of modular structure:
my_custom_theme/
├── styles.py
├── metainfo.ini
├── fonts/
├── images/
└── styles/ # This can be named anything (e.g., components, modules, etc.)
├── __init__.py # This empty file makes the directory a Python package
├── constants.py
├── base.py
├── game_card.py
├── detail_page.py
├── settings.py
├── winetricks.py
└── theme_utils.py
Main styles.py file:
You can use either absolute imports (recommended for built-in themes):
# Import from the theme's submodules using absolute paths relative to the package
# Replace 'my_custom_theme' with your actual theme folder name and 'styles' with your subdirectory name
from portprotonqt.themes.my_custom_theme.styles.constants import *
from portprotonqt.themes.my_custom_theme.styles.base import *
from portprotonqt.themes.my_custom_theme.styles.game_card import *
from portprotonqt.themes.my_custom_theme.styles.detail_page import *
from portprotonqt.themes.my_custom_theme.styles.settings import *
from portprotonqt.themes.my_custom_theme.styles.winetricks import *
from portprotonqt.themes.my_custom_theme.styles.theme_utils import *
Or you can use relative imports (recommended for custom user themes):
# Import from the theme's submodules using relative paths
from .styles.constants import *
from .styles.base import *
from .styles.game_card import *
from .styles.detail_page import *
from .styles.settings import *
from .styles.winetricks import *
from .styles.theme_utils import *
Example submodule (styles/constants.py):
# Theme constants
font_family = "Play"
font_size_a = "16px"
font_size_b = "24px"
border_radius_a = "10px"
color_a = "#409EFF"
color_b = "#282a33"
# ... other constants
🧬 Style Inheritance
Themes can inherit missing style variables and functions from another theme by defining THEME_INHERITS in styles.py:
THEME_INHERITS = "classic"
If THEME_INHERITS is not defined, the theme inherits styles from standart.
Inheritance applies only to style attributes loaded from styles.py. Fonts, icons, images, and screenshots do not inherit from THEME_INHERITS; their fallback remains the built-in standart theme.
🧩 Library Layout Mode
You can control the game library card layout directly from the theme via styles.py:
# "grid" (default) or "list"
LIBRARY_LAYOUT_MODE = "grid"
grid: multi-column card grid (classic behavior).list: horizontal row-style cards (launcher-style list).
This is a theme-level option and does not depend on app settings.
🧾 Detail Page Layout Mode
You can control the detail page layout from the theme via styles.py:
# "full" (default) or "compact"
DETAIL_PAGE_LAYOUT_MODE = "full"
full: full cover size, description, badges, controller support, and HowLongToBeat data.compact: smaller cover and simplified detail content.
Economy mode also forces the compact detail page layout.
🎥 Animation configuration
The GAME_CARD_ANIMATION dictionary controls all animation parameters for game cards:
GAME_CARD_ANIMATION = {
# Type of animation when entering or exiting the detail page
# Possible values: "fade", "slide_left", "slide_right", "slide_up", "slide_down", "bounce"
# Determines how the detail page appears and disappears
"detail_page_animation_type": "fade",
# Border width of the card in idle state (no hover or focus)
# Affects the thickness of the border around the card when it's not selected
# Value in pixels
"default_border_width": 2,
# Border width on hover
# Increases the border thickness when the cursor is over the card
# Value in pixels
"hover_border_width": 8,
# Border width on focus (e.g., when selected via keyboard)
# Increases the border thickness when the card is focused
# Value in pixels
"focus_border_width": 12,
# Minimum border width during pulsing animation
# Determines the minimum border thickness during the "breathing" animation
# Value in pixels
"pulse_min_border_width": 8,
# Maximum border width during pulsing animation
# Determines the maximum border thickness during pulsing
# Value in pixels
"pulse_max_border_width": 10,
# Duration of the border thickness animation (e.g., on hover or focus)
# Affects the speed of transition from one border width to another
# Value in milliseconds
"thickness_anim_duration": 300,
# Duration of one pulsing animation cycle
# Determines how fast the border "pulses" between min and max values
# Value in milliseconds
"pulse_anim_duration": 800,
# Duration of the gradient rotation animation
# Affects how fast the gradient border rotates around the card
# Value in milliseconds
"gradient_anim_duration": 3000,
# Starting angle of the gradient (in degrees)
# Determines the initial rotation point of the gradient at animation start
"gradient_start_angle": 360,
# Ending angle of the gradient (in degrees)
# Determines the final rotation point of the gradient
# Value 0 means a full 360° rotation
"gradient_end_angle": 0,
# Type of card animation on hover or focus
# Possible values: "gradient", "scale", "fill", "stripe", "glow", "scale_fill"
# "gradient" enables a rotating gradient border, "scale" enlarges the card,
# "fill" applies a static overlay, "stripe" applies a static border color,
# "glow" adds pulsing border glow, "scale_fill" combines scaling + fill
"card_animation_type": "gradient",
# Overlay color for "fill" animation type
# Any valid Qt color string (hex/rgb/rgba)
"fill_color": color_a,
# Overlay opacity for "fill" animation type (0-255)
"fill_alpha": 90,
# Border color for "stripe" animation type
# Any valid Qt color string (hex/rgb/rgba)
"stripe_color": color_a,
# Border opacity for "stripe" animation type (0-255)
"stripe_alpha": 255,
# Base opacity for "glow" animation type (0-255)
"glow_base_alpha": 120,
# Extra pulse opacity for "glow" animation type (0-255)
"glow_pulse_alpha": 80,
# Card scale in idle state
# Determines the base size of the card (1.0 = 100% of original size)
# Value as a fraction (e.g., 1.0 for normal size)
"default_scale": 1.0,
# Card scale on hover
# Increases the card size on hover
# Value as a fraction (e.g., 1.1 = 110% of original size)
"hover_scale": 1.1,
# Card scale on focus (e.g., when selected via keyboard)
# Increases the card size on focus
# Value as a fraction (e.g., 1.05 = 105% of original size)
"focus_scale": 1.05,
# Duration of scale animation
# Affects how fast the card changes size on hover or focus
# Value in milliseconds
"scale_anim_duration": 200,
# Easing curve type for border thickness increase animation (on hover/focus)
# Affects the "feel" of the animation (e.g., smooth acceleration or deceleration)
# Possible values: strings corresponding to QEasingCurve.Type (e.g., "OutBack", "InOutQuad")
"thickness_easing_curve": "OutBack",
# Easing curve type for border thickness decrease animation (on hover/focus exit)
# Affects the "feel" of returning to the default border width
"thickness_easing_curve_out": "InBack",
# Easing curve type for scale increase animation (on hover/focus)
# Affects the "feel" of the scaling animation (e.g., with a "bounce" effect)
# Possible values: strings corresponding to QEasingCurve.Type
"scale_easing_curve": "OutBack",
# Easing curve type for scale decrease animation (on hover/focus exit)
# Affects the "feel" of returning to the original scale
"scale_easing_curve_out": "InBack",
# Gradient colors for animated border
# List of dictionaries, each specifying position (0.0–1.0) and color in hex format
# Affects the appearance of the border on hover or focus if card_animation_type="gradient"
"gradient_colors": [
{"position": 0, "color": "#00fff5"}, # Starting color (cyan)
{"position": 0.33, "color": "#FF5733"}, # Color at 33% (orange)
{"position": 0.66, "color": "#9B59B6"}, # Color at 66% (purple)
{"position": 1, "color": "#00fff5"} # Ending color (back to cyan)
],
# Duration of fade animation when entering the detail page
# Affects the speed of page appearance with fade animation
# Value in milliseconds
"detail_page_fade_duration": 350,
# Duration of slide animation when entering the detail page
# Affects the speed of page sliding animation
# Value in milliseconds
"detail_page_slide_duration": 500,
# Duration of bounce animation when entering the detail page
# Affects the speed of page "bounce" animation
# Value in milliseconds
"detail_page_bounce_duration": 400,
# Duration of fade animation when exiting the detail page
# Affects the speed of page disappearance with fade animation
# Value in milliseconds
"detail_page_fade_duration_exit": 350,
# Duration of slide animation when exiting the detail page
# Affects the speed of page sliding animation
# Value in milliseconds
"detail_page_slide_duration_exit": 500,
# Duration of bounce animation when exiting the detail page
# Affects the speed of page "compression" animation
# Value in milliseconds
"detail_page_bounce_duration_exit": 400,
# Easing curve type for animations when entering the detail page
# Applied to slide and bounce animations; affects the "feel" of movement
# Possible values: strings corresponding to QEasingCurve.Type
"detail_page_easing_curve": "OutCubic",
# Easing curve type for animations when exiting the detail page
# Applied to slide and bounce animations; affects the "feel" of movement
# Possible values: strings corresponding to QEasingCurve.Type
"detail_page_easing_curve_exit": "InCubic"
}
Virtual keyboard animation options are configured with theme-level constants:
virtual_keyboard_animation_type = "slide" # "slide", "fade", "slide_fade", "slide_bounce"
virtual_keyboard_slide_animation_duration = 160
virtual_keyboard_fade_animation_duration = 140
virtual_keyboard_slide_fade_animation_duration = 180
virtual_keyboard_slide_bounce_animation_duration = 220
📝 Metadata (metainfo.ini)
[Metainfo]
name_en = My Custom Theme
name_ru = Моя пользовательская тема
author = Your Name
author_link = https://example.com
description_en = Description of your theme.
description_ru = Описание вашей темы.
Translation Support
You must provide translations for your theme's name and description by adding language-specific fields:
name_en,name_ru, etc. for theme namesdescription_en,description_ru, etc. for theme descriptions
The application will automatically select the appropriate translation based on the user's system language, falling back to English if translations are not available for the user's language.
🖼 Screenshots
Folder: images/screenshots/ — place UI screenshots there.
Screenshot files can have any convenient names.
🔡 Fonts and Icons (optional)
- Fonts:
fonts/*.ttfor.otf - Icons and Images:
images/directory for all visual assets. Supported formats:.svg,.png,.jpg,.jpeg,.webp,.jxl.images/icons/- Main application icons (organized in subdirectories like actions/, navigation/, platforms/, etc.)images/icons/buttons/- Button icons for UI elementsimages/icons/keyboards/- Keyboard key icons (key_+, key_enter, etc.)images/icons/controllers/- Controller button iconsimages/icons/controllers/xbox/- Xbox controller button icons (xbox_a, xbox_b, etc.)images/icons/controllers/playstation/- PlayStation controller button icons (ps_circle, ps_cross, etc.)images/ui_elements/- UI elements (placeholder images, etc.)images/screenshots/- Theme preview screenshots
Icons and images can be referenced by name without specifying the subdirectory, as the system will search through all subdirectories automatically. Theme creators can organize images in any logical subdirectory structure.