OpenParable
Skip to content
← Back to skills

Maui Theming

Design
maui-theming

Maui Theming is an Agent Skill for design published in the davidortinau/maui-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/davidortinau/maui-skills/blob/HEAD/plugins/maui-skills/skills/maui-theming/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/maui-theming, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

.NET MAUI Theming

Choosing your approach

ApproachBest forLimitation
AppThemeBindingAuto light/dark with OS — minimal codeOnly two themes (light + dark)
ResourceDictionary swapCustom branded themes, >2 themes, user preferenceMore setup, must use DynamicResource everywhere
Both combinedAuto OS response + custom theme colorsMost 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 → AppThemeBinding markup extension
  • Theme colors in C# → SetAppThemeColor(), SetAppTheme<T>()
  • Read OS theme → Application.Current.RequestedTheme
  • Force theme → Application.Current.UserAppTheme = AppTheme.Dark
  • Theme changes → RequestedThemeChanged event
  • Custom switching → Swap ResourceDictionary in MergedDictionaries
  • Runtime bindings → DynamicResource (not StaticResource)