maui-theming
Guide for theming .NET MAUI apps—light/dark mode support, AppThemeBinding, dynamic resources, ResourceDictionary theme switching, and system theme detection. USE FOR: "dark mode", "light mode", "theming", "AppThemeBinding", "theme switching", "ResourceDictionary theme", "dynamic resources", "system theme detection", "color scheme", "app theme". DO NOT USE FOR: localization or language switching (use maui-localization), accessibility visual adjustments (use maui-accessibility), or app icons (use maui-app-icons-splash).
How do I install this agent skill?
npx skills add https://github.com/davidortinau/maui-skills --skill maui-themingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a safe technical guide for .NET MAUI theming. It provides documentation and standard code snippets for handling light/dark modes, resource dictionaries, and system theme detection without any security risks identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
.NET MAUI Theming
Choosing your approach
| Approach | Best for | Limitation |
|---|---|---|
| AppThemeBinding | Auto light/dark with OS — minimal code | Only two themes (light + dark) |
| ResourceDictionary swap | Custom branded themes, >2 themes, user preference | More setup, must use DynamicResource everywhere |
| Both combined | Auto OS response + custom theme colors | Most flexible but most complex |
Critical gotchas
Android: ConfigChanges.UiMode is REQUIRED
MainActivity must include ConfigChanges.UiMode or theme change events will
not fire and the activity restarts instead of handling the change:
[Activity(Theme = "@style/Maui.SplashTheme",
MainLauncher = true,
ConfigurationChanges = ConfigChanges.ScreenSize
| ConfigChanges.Orientation
| ConfigChanges.UiMode // ← Required for theme detection
| ConfigChanges.ScreenLayout
| ConfigChanges.SmallestScreenSize
| ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity { }
Without UiMode, toggling dark mode in Android settings causes a full activity
restart — losing navigation state and appearing as a crash to users.
CSS themes cannot be swapped at runtime
MAUI supports CSS styling, but CSS-based themes cannot be swapped dynamically. Use ResourceDictionary theming for runtime switching.
DynamicResource vs StaticResource
When using ResourceDictionary theme switching, you must use DynamicResource:
<!-- ✅ Updates when theme dictionary changes -->
<Label TextColor="{DynamicResource PrimaryTextColor}" />
<!-- ❌ Frozen at first load — won't update on theme switch -->
<Label TextColor="{StaticResource PrimaryTextColor}" />
Quick reference
- OS light/dark →
AppThemeBindingmarkup extension - Theme colors in C# →
SetAppThemeColor(),SetAppTheme<T>() - Read OS theme →
Application.Current.RequestedTheme - Force theme →
Application.Current.UserAppTheme = AppTheme.Dark - Theme changes →
RequestedThemeChangedevent - Custom switching → Swap
ResourceDictionaryinMergedDictionaries - Runtime bindings →
DynamicResource(notStaticResource)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/davidortinau/maui-skills/maui-theming">View maui-theming on skillZs</a>