sli-ui-toolkit 0.3.0

Reusable PySide6 UI toolkit primitives for SLI desktop tools.

SLI UI Toolkit

Reusable PySide6 widgets and UI infrastructure for compact desktop tools.

SLI stands for Shared Lightweight Interface. The toolkit was extracted from Improve-ImgSLI and Tkonverter, but host-specific icons, translations, resources, and business logic stay outside the library.

What Is Included

• custom-painted compact controls: buttons, inputs, switches, sliders, labels;
• a unified Button system with icons, text, toggle, scroll, menu, long-press, ripple, and multi-region split layouts;
• reusable composite widgets: flyouts, dialog shells, markdown help, timelines, toasts, lists, charts;
• theme-aware painting through ThemeManager tokens;
• app-injected hooks for icons, i18n, overlay placement, and timing.

Install

For development from this repository:

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

For use as a dependency:

python -m pip install sli-ui-toolkit

Run The Demo

From the repository root:

python -m demo

The demo opens a PyQt window with widget pages for buttons, inputs, lists, dialogs, flyouts, charts, feedback, and miscellaneous primitives.

If you run on a headless machine, set Qt's platform first:

QT_QPA_PLATFORM=offscreen python -m demo

Run Tests

pytest tests/

The test suite uses pytest-qt and defaults to offscreen Qt through tests/conftest.py.

Basic Use

Most application code should import from sli_ui_toolkit.widgets.

from PySide6.QtWidgets import QApplication, QVBoxLayout, QWidget

from sli_ui_toolkit.theme import ThemeManager
from sli_ui_toolkit.widgets import Button, ComboBox

app = QApplication([])

theme = ThemeManager.get_instance()
theme.set_theme("light", app)

window = QWidget()
layout = QVBoxLayout(window)

save = Button("save", text="Save", variant="surface")
mode = ComboBox()
mode.addItems(["Fast", "Balanced", "Quality"])

layout.addWidget(save)
layout.addWidget(mode)
window.show()

app.exec()

App Configuration Hooks

Hosts can inject app-specific behavior at startup:

• configure_icon_resolver(...) Supplies icon lookup for app icon enums, names, or resources.
• configure_toolkit(...) Supplies overlay placement and timing defaults for flyouts and popups.
• configure_i18n(...) Supplies translation roots and language handling.

Minimal apps can use bundled toolkit icons and skip these hooks. Larger host apps should configure them once during startup.

Public Import Layers

• sli_ui_toolkit Bootstrap/configuration helpers and common primitives.
• sli_ui_toolkit.widgets Main public widget catalog. Prefer this for application UI.
• sli_ui_toolkit.theme ThemeManager.
• sli_ui_toolkit.icons Icon resolver configuration.
• sli_ui_toolkit.i18n Translation manager and helpers.
• sli_ui_toolkit.managers Flyout and timer helpers.
• sli_ui_toolkit.services Utility services such as prewarm helpers.

Everything under sli_ui_toolkit.ui... is implementation detail first. Use it inside toolkit internals, or only when no public export exists yet.

Documentation

• User docs
• Full public API
• Button API
• Developer docs
• Architecture
• Design language
• Docs index

Development Notes

• Keep host-app behavior outside the toolkit. Pass behavior through callbacks, signals, configuration hooks, or plain data objects.
• Resolve colors and sizes through ThemeManager, widget properties, or documented tokens.
• Update docs when changing public widget behavior or public API.
• Run pytest tests/ before publishing or tagging a release.

Caveats

• ComboBox is custom-painted; it is not a full QComboBox drop-in replacement.
• The toolkit is designed around custom-painted controls, not QSS-skinned stock widgets.
• Light and dark themes are both first-class. Avoid hard-coded colors in custom widgets; use theme tokens.