ThemeColors

ThemeColors is an all-static utility class that centralizes color management for Blackchirp’s user interface. Every color it returns is derived from the active system palette and adjusted so that status indicators, accent text, and SVG icons remain readable under both light and dark system themes. It is the right starting point for any new UI surface that requires a theme-respecting accent color or a status-feedback color.

Color roles

The ColorRole enum divides the available colors into three families:

Status colors — used for feedback and state indicators:

StatusSuccess — valid states and success messages.
StatusWarning — caution states and warning messages.
StatusError — invalid states and error messages.
StatusInfo — informational or neutral-positive messages.
StatusNeutral — default or unclassified status.

Text colors — used for emphasis levels in labels and tooltips:

SubtleText — secondary or less-important text.
EmphasisText — highlighted or important text.
DisabledText — inactive or disabled text. Also used as the default color role for the disabled state in createThemedIconWithStates().

Icon colors — used when rendering SVG icons:

IconPrimary — main interface element icons.
IconSecondary — supporting or secondary icons.
IconAccent — special-highlight icons.

Palette-derived colors and CSS

getThemeAwareColor(role, widget) returns a QColor appropriate for the current theme. Pass a widget pointer to use that widget’s palette for context; pass nullptr to fall back to the application palette. getCSSColor() returns the same color as a hex string (e.g., "#1a9e3f") suitable for use in Qt stylesheets.

isDarkTheme(widget) inspects the palette and returns true when a dark system theme is active. UI code that renders custom graphics can use this to choose appropriate base colors before calling getThemeAwareColor().

Contrast helpers

ensureContrast(color, background, minContrastRatio) adjusts color until its WCAG contrast ratio against background meets minContrastRatio. The default target of 4.5 corresponds to WCAG AA compliance for normal-weight text. calculateContrastRatio(color1, color2) performs the raw calculation; the ratio ranges from 1.0 (identical colors) to 21.0 (black on white).

SVG icon helpers

createThemedIcon(svgPath, colorRole, widget) loads an SVG from a Qt resource path and recolors it using the color for colorRole, returning a QIcon sized for the platform’s icon metrics. createThemedIconWithStates(svgPath, enabledRole, disabledRole, widget) produces a QIcon with separate colors for enabled and disabled states, which Qt uses automatically when a toolbar button or menu action is disabled.

API Reference

class ThemeColors

All-static utility class for theme-aware colors and icons.

Every color is derived from the system palette and adjusted for contrast so that status indicators and icons remain readable under both light and dark system themes.