UI Components

YASB includes a built-in UI component system based on WinUI3 design tokens. These components handle theming, animations, and accessibility automatically. Use them when building widgets that need dialogs, buttons, toggles, or other interactive elements.

All components live in src/core/ui/components/ and share the same token-based theming from src/core/ui/tokens.py.

Design Tokens

The token system provides ~150 color tokens organized by theme (dark / light). Values are sourced from the WinUI3 Common_themeresources_any.xaml.

from core.ui.theme import get_tokens, theme_key, is_dark, FONT_FAMILIES

tokens = get_tokens()          # Returns dict for current OS theme
tokens["text_primary"]         # "#ffffff" (dark) or "#e3000000" (light)
tokens["accent_fill_default"]  # "#4cc2ff" (dark) or "#0078d4" (light)

Token Categories

Theme Reactivity

All components respond to OS theme changes automatically. To make your own widget theme-reactive:

from core.ui.theme import get_tokens, theme_key

class MyWidget(QWidget):
    def __init__(self):
        super().__init__()
        self._theme_key = theme_key()
        self._apply_styles()
        QApplication.instance().paletteChanged.connect(self._on_theme_changed)

    def _on_theme_changed(self):
        key = theme_key()
        if key == self._theme_key:
            return
        self._theme_key = key
        self._apply_styles()

    def _apply_styles(self):
        tokens = get_tokens()
        self.setStyleSheet(f"color: {tokens['text_primary']};")

Components

Button

Interactive button with three variants and animated state transitions.

from core.ui.components.button import Button

Parameters:

Variants:

Example:

save_btn = Button("Save", variant="accent", parent=self)
save_btn.setFixedHeight(32)
save_btn.clicked.connect(self._on_save)

cancel_btn = Button("Cancel", variant="default", parent=self)
cancel_btn.clicked.connect(self._on_cancel)

TextBlock

Themed label with preset typography variants matching WinUI3 type ramp.

from core.ui.components.text_block import TextBlock

Parameters:

Variants:

Example:

title = TextBlock("Settings", variant="subtitle", parent=self)
description = TextBlock("Configure your preferences.", variant="body-secondary", parent=self)

ToggleSwitch

Animated on/off switch matching the WinUI3 toggle.

from core.ui.components.toggle_switch import ToggleSwitch, ToggleSwitchWithLabel

Parameters:

Signals:

• toggled(bool) — Emitted when the switch state changes.

Example:

toggle = ToggleSwitch(checked=False, parent=self)
toggle.toggled.connect(lambda on: print(f"Switch: {on}"))

# With label:
toggle = ToggleSwitchWithLabel(
    text="Dark Mode",
    on_text="Enabled",
    off_text="Disabled",
    checked=True,
    parent=self,
)

Card

Selectable card container with hover and selection states.

from core.ui.components.card import Card

Parameters:

Methods:

• set_selected(selected: bool) — Toggle the accent selection state.
• is_selected() -> bool — Check if currently selected.

Example:

card = Card(parent=self)
card_layout = QVBoxLayout(card)
card_layout.addWidget(QLabel("Option A"))
card.set_selected(True)

ContentDialog

Modal overlay dialog that centers on a parent widget with a smoke layer. Best suited for views and panels. For bar widgets, use InputDialog instead.

from core.ui.components.content_dialog import ContentDialog, ContentDialogButton, ContentDialogResult

Parameters:

Signals:

• primary_button_click — Primary button clicked.
• secondary_button_click — Secondary button clicked.
• close_button_click — Close button clicked.
• closed(ContentDialogResult) — Dialog closed with result (PRIMARY, SECONDARY, or NONE).

Example:

dlg = ContentDialog(
    parent=self,
    title="Delete Item?",
    content="This action cannot be undone.",
    primary_button_text="Delete",
    close_button_text="Cancel",
    default_button=ContentDialogButton.PRIMARY,
)
dlg.primary_button_click.connect(self._delete_item)
dlg.show_dialog()

InputDialog

Standalone input dialog that appears at the cursor position. Uses DWM blur and rounded corners. Does not require a parent widget — ideal for bar widgets and context menu actions.

from core.ui.components.input_dialog import InputDialog

Parameters:

Signals:

• accepted(str) — User pressed the primary button (emits trimmed text).
• rejected() — User cancelled or pressed Escape.

Example:

dlg = InputDialog(
    title="Rename Desktop",
    content="Enter a new name for this desktop.",
    text="Desktop 1",
    primary_button_text="Rename",
    close_button_text="Cancel",
)
dlg.accepted.connect(lambda name: print(f"Renamed to: {name}"))
dlg.show_dialog()

DropDown

Styled dropdown selector with a blurred popup.

from core.ui.components.dropdown import DropDown

Parameters:

Signals:

• currentChanged(str) — Emitted when selection changes (provides the key).

Example:

dd = DropDown(
    items=[("en", "English"), ("de", "German"), ("ja", "Japanese")],
    parent=self,
)
dd.set_current("en")
dd.currentChanged.connect(lambda key: print(f"Language: {key}"))

Slider

Horizontal slider with a value label and accent-colored track.

from core.ui.components.slider import Slider

Parameters:

Signals:

• valueChanged(int) — Emitted when the value changes.

Example:

slider = Slider(minimum=0, maximum=100, value=75, suffix="%", parent=self)
slider.valueChanged.connect(lambda v: print(f"Volume: {v}%"))

InfoBar

Status notification bar with severity levels and corresponding icons.

from core.ui.components.info_bar import InfoBar, InfoBarSeverity

Parameters:

Severity Levels:

Example:

bar = InfoBar(
    title="Saved",
    message="Your settings have been saved.",
    severity=InfoBarSeverity.SUCCESS,
    parent=self,
)

StepIndicator

Animated horizontal step indicator (dot/dash style).

from core.ui.components.indicator import StepIndicator

Parameters:

Methods:

• set_current(index: int) — Animate to a step (0-indexed).

Example:

indicator = StepIndicator(count=4, parent=self)
indicator.set_current(0)  # First step active

Link

Hyperlink-styled button using accent text colors.

from core.ui.components.link import Link

Parameters:

Example:

link = Link("Learn more", parent=self)
link.clicked.connect(self._open_docs)

Loader

Two loading indicator variants: circular spinner and horizontal progress line.

from core.ui.components.loader import Spinner, LoaderLine

Spinner

spinner = Spinner(size=24, color="#4cc2ff", parent=self)

LoaderLine

loader = LoaderLine(parent=self)
loader.attach_to_widget(target_widget)  # Auto-positions at bottom edge
loader.start()
# ...
loader.stop()

Tips for Contributors

• Always use tokens — never hardcode colors. Use get_tokens() to look up the current theme values.
• React to theme changes — connect to QApplication.instance().paletteChanged and re-apply styles when the OS theme switches.
• Use FONT_FAMILIES — import from core.ui.theme instead of hardcoding "Segoe UI".
• Prefer existing components — check if a component already exists before creating a new one. The system is designed to be reusable.