Synaptipy Styling Guide

This document explains the styling system used in Synaptipy, how it’s organized, and how to ensure consistent UI styling in your code.

Overview

Synaptipy uses Qt’s native theming system (src/Synaptipy/shared/styling.py) for consistent application appearance. The styling system is designed to:

  1. Ensure visual consistency throughout the application using Qt’s built-in palette system

  2. Support seamless light/dark theme switching

  3. Provide convenient helpers for PyQtGraph visualization styling

  4. Minimize custom styling in favor of native Qt appearance

Key Components

Theme Mode Management

The styling module provides simple theme management functions:

  • get_current_theme_mode(): Returns current theme (‘light’ or ‘dark’)

  • set_theme_mode(mode): Set theme to ‘light’ or ‘dark’

  • toggle_theme_mode(): Switch between light and dark themes

Qt Native Theming

The system uses Qt’s native palette and style system:

  • Dark Theme: Uses “Fusion” style with custom dark palette

  • Light Theme: Uses system native style with default palette

PyQtGraph Plot Styling

Specialized functions for plot appearance:

  • configure_plot_widget(plot_widget): Apply theme-appropriate colors to plots

  • get_trial_pen(), get_average_pen(): Get theme-appropriate pens for data

  • get_baseline_pen(), get_response_pen(): Get pens for analysis indicators

  • get_grid_pen(): Get theme-appropriate grid line styling

Simple Widget Styling

Minimal styling helpers that work with Qt’s native theming:

  • style_button(button, style='primary'): Apply simple button styling

  • style_label(label, style='normal'): Apply label styling (heading, subheading)

  • style_info_label(label): Style informational labels

  • style_error_message(widget): Style error messages

Theme Application

  • apply_stylesheet(app): Apply the current theme to the entire application

How to Use

For General UI Elements

Use the minimal styling helpers when needed:

from PySide6 import QtWidgets
from Synaptipy.shared.styling import style_button, style_label

# Create widgets
button = QtWidgets.QPushButton("Save")
info_label = QtWidgets.QLabel("Select a file to analyze")

# Apply minimal styling (mostly relies on Qt's native theming)
style_button(button, 'primary') # Makes button slightly more prominent
style_label(info_label, 'heading') # Makes label bold and larger

For PyQtGraph Elements

Use the PyQtGraph helper functions:

import pyqtgraph as pg
from Synaptipy.shared.styling import configure_plot_widget, get_trial_pen, get_average_pen

# Create plot widget with theme-appropriate styling
plot_widget = pg.PlotWidget()
configure_plot_widget(plot_widget)

# Plot data with theme-appropriate pens
plot_widget.plot(time, trial_data, pen=get_trial_pen())
plot_widget.plot(time, avg_data, pen=get_average_pen())

For Theme Switching

Theme switching is handled automatically by the main window, but can be controlled programmatically:

from Synaptipy.shared.styling import set_theme_mode, toggle_theme_mode, apply_stylesheet
from PySide6 import QtWidgets

# Switch to dark theme
set_theme_mode('dark')
app = QtWidgets.QApplication.instance()
apply_stylesheet(app)

# Or toggle theme
new_mode = toggle_theme_mode()
apply_stylesheet(app)

Best Practices

  1. Rely on Qt’s native theming - Avoid custom stylesheets when possible

  2. Use the theme helper functions for plot styling and minimal widget customization

  3. Let Qt handle most styling - The palette system automatically handles colors for most widgets

  4. Test both themes - Always verify your UI works well in both light and dark modes

  5. Keep styling minimal - Add custom styling only when necessary for functionality

Architecture Benefits

The new Qt native theming approach provides:

  1. Better OS Integration: Matches system appearance expectations

  2. Reduced Complexity: Fewer custom stylesheets to maintain

  3. Improved Performance: Qt’s native rendering is optimized

  4. Better Accessibility: Native theming supports system accessibility features

  5. Future Compatibility: Less dependent on external styling libraries

Migration from Previous System

The previous complex custom styling system has been replaced with this simpler approach:

  • Removed: Complex custom stylesheets, qdarkstyle dependency, custom color palettes

  • Replaced: Qt native palettes with minimal custom styling for specific needs

  • Maintained: Plot styling helpers and basic widget styling functions