```cpp
// semantic color roles (look colors up by ROLE, not by control)
enum class ThemeRole { Text, TextSecondary, TextDisabled, TextOnAccent,
Surface, SurfaceAlt, SurfaceRaised, Backdrop, Overlay,
Control, ControlHover, ControlPressed, ControlDisabled,
Accent, AccentHover, AccentPressed,
Border, Divider, FocusRing, Selection,
ScrollTrack, ScrollThumb, ScrollThumbHover,
Danger, Warning, Success, Info, Shadow, Count };
struct Theme { Color colors[(int)ThemeRole::Count]; FontSpec font, fontCaption, fontMono;
float cornerRadius; bool isDark; std::wstring name;
Color Get(ThemeRole) const; void Set(ThemeRole, Color);
static Theme Light(); static Theme Dark(); static Theme HighContrast(); };
// app level
void ThemeManager::SetAppTheme(const Theme&); void ThemeManager::SetLight/DarkAppTheme();
Theme& ThemeManager::AppTheme(); bool ThemeManager::IsDark();
// follow system (registry AppsUseLightTheme + DWM AccentColor; auto re-resolve on WM_SETTINGCHANGE etc.)
void ThemeManager::SetFollowSystem(bool); bool ThemeManager::IsFollowingSystem();
bool ThemeManager::SystemPrefersDark(); Color ThemeManager::SystemAccent(); Theme ThemeManager::SystemTheme();
// test hook: emulate the system theme (bypass the registry)
void ThemeManager::DebugForceSystemTheme(bool enable, bool dark, bool highContrast);
// color remap: any hard-coded color → theme color (exact table; passthrough + keeps alpha on miss)
void ThemeManager::SetColorMap(std::unordered_map<uint32_t, Color>); Color ThemeManager::Map(Color);
// Hook registration: returns a RAII HookHandle (auto-disconnect on destruction); own fixed hooks use RegisterHookPermanent.
HookHandle ThemeManager::RegisterHook(std::function<void(const Theme&)>);
HookHandle ThemeManager::RegisterSubtreeApplier(std::function<void(UIElement*, const Theme&)>);
// debug: theme name + each Role as AARRGGBB (debug channel cmd 23 GetTheme)
std::wstring ThemeManager::Dump();
// window level
void Window::SetTheme(const Theme&); const Theme& Window::GetTheme();
void Window::SetUseAppTheme(bool = true); bool Window::IsUsingAppTheme(); void Window::RefreshTheme();
ZSignal<Window*> UIZSignals::ThemeChanged; // nullptr = app-wide
ZSignal<Window*> UIZSignals::ThemeReapply; // re-apply to visible subtree after page/tab switch
```
- Color priority: **explicit instance color > window theme > app theme**. Once a control's `Set*Color` is called explicitly it is flagged "user-colored" and the theme **no longer overrides it**; all other controls follow the theme.
###block_red_start
**Pitfall**
- `Backdrop` is the **window/background base color** (white in light, black in dark); after an explicit `SetBackdrop/SetBackgroundColor` tint, the theme no longer changes it.
###block_red_end
- **`Version`**: introduced in `v1.19.0`; window periphery (caption buttons) follows the **system** theme, not the window theme; `WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGE` auto re-resolve.Theme system
Theme (v1.19.0+)
cpp
// semantic color roles (look colors up by ROLE, not by control)
enum class ThemeRole { Text, TextSecondary, TextDisabled, TextOnAccent,
Surface, SurfaceAlt, SurfaceRaised, Backdrop, Overlay,
Control, ControlHover, ControlPressed, ControlDisabled,
Accent, AccentHover, AccentPressed,
Border, Divider, FocusRing, Selection,
ScrollTrack, ScrollThumb, ScrollThumbHover,
Danger, Warning, Success, Info, Shadow, Count };
struct Theme { Color colors[(int)ThemeRole::Count]; FontSpec font, fontCaption, fontMono;
float cornerRadius; bool isDark; std::wstring name;
Color Get(ThemeRole) const; void Set(ThemeRole, Color);
static Theme Light(); static Theme Dark(); static Theme HighContrast(); };
// app level
void ThemeManager::SetAppTheme(const Theme&); void ThemeManager::SetLight/DarkAppTheme();
Theme& ThemeManager::AppTheme(); bool ThemeManager::IsDark();
// follow system (registry AppsUseLightTheme + DWM AccentColor; auto re-resolve on WM_SETTINGCHANGE etc.)
void ThemeManager::SetFollowSystem(bool); bool ThemeManager::IsFollowingSystem();
bool ThemeManager::SystemPrefersDark(); Color ThemeManager::SystemAccent(); Theme ThemeManager::SystemTheme();
// test hook: emulate the system theme (bypass the registry)
void ThemeManager::DebugForceSystemTheme(bool enable, bool dark, bool highContrast);
// color remap: any hard-coded color → theme color (exact table; passthrough + keeps alpha on miss)
void ThemeManager::SetColorMap(std::unordered_map<uint32_t, Color>); Color ThemeManager::Map(Color);
// Hook registration: returns a RAII HookHandle (auto-disconnect on destruction); own fixed hooks use RegisterHookPermanent.
HookHandle ThemeManager::RegisterHook(std::function<void(const Theme&)>);
HookHandle ThemeManager::RegisterSubtreeApplier(std::function<void(UIElement*, const Theme&)>);
// debug: theme name + each Role as AARRGGBB (debug channel cmd 23 GetTheme)
std::wstring ThemeManager::Dump();
// window level
void Window::SetTheme(const Theme&); const Theme& Window::GetTheme();
void Window::SetUseAppTheme(bool = true); bool Window::IsUsingAppTheme(); void Window::RefreshTheme();
ZSignal<Window*> UIZSignals::ThemeChanged; // nullptr = app-wide
ZSignal<Window*> UIZSignals::ThemeReapply; // re-apply to visible subtree after page/tab switch
- Color priority: explicit instance color > window theme > app theme. Once a control's
Set*Coloris called explicitly it is flagged "user-colored" and the theme no longer overrides it; all other controls follow the theme.
Pitfall
Backdropis the window/background base color (white in light, black in dark); after an explicitSetBackdrop/SetBackgroundColortint, the theme no longer changes it.
Version: introduced inv1.19.0; window periphery (caption buttons) follows the system theme, not the window theme;WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGEauto re-resolve.