maui-theming skill | PlugMCP

maui-theming

by dotnet5.7k

Install

The skill file stays in the publisher's repository.

Paste the copied command in a terminal. It installs this SKILL.md into that agent.

npx skills add dotnet/skills --skill maui-theming -a cursor -y

Download skill plugins/dotnet-maui/skills/maui-theming/SKILL.md on GitHub

Related skills

View all

Questions

How do I install maui-theming?: Download plugins/dotnet-maui/skills/maui-theming/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does maui-theming live?: The publisher keeps it at https://github.com/dotnet/skills.
Which agents can use maui-theming?: Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.

name: maui-theming description: >- Guide for theming .NET MAUI apps — light/dark mode via AppThemeBinding, ResourceDictionary theme switching, DynamicResource bindings, system theme detection, and user theme preferences. Use when: "dark mode", "light mode", "theming", "AppThemeBinding", "theme switching", "ResourceDictionary theme", "dynamic resources", "system theme detection", "color scheme", "app theme", "DynamicResource". Do not use for: localization or language switching (see .NET MAUI localization documentation), accessibility visual adjustments (see .NET MAUI accessibility documentation), app icons or splash screens (see .NET MAUI app icons documentation), or Bootstrap-style class theming (see Plugin.Maui.BootstrapTheme NuGet package). license: MIT

.NET MAUI Theming

Apply light/dark mode support, custom branded themes, and runtime theme switching in .NET MAUI apps using AppThemeBinding, ResourceDictionary swapping, and system theme detection APIs.

When to Use

Rule	Do this	Not this	Why
Runtime-swapped values must be dynamic	`{DynamicResource Key}`	`{StaticResource Key}`	`StaticResource` resolves once at load and never updates when dictionaries are swapped.
Android must declare `UiMode` (only for runtime/system theme switching)	Include `ConfigChanges.UiMode` in the `ConfigurationChanges` list on `MainActivity`	Omitting it	Without it Android restarts the activity on theme change — navigation state is lost and it looks like a crash. Irrelevant to a static `AppThemeBinding` setup
Force a theme via `UserAppTheme`	`Application.Current.UserAppTheme = AppTheme.Dark`	Manually re-assigning colors	`UserAppTheme` overrides the OS; `AppTheme.Unspecified` returns to following the system.

Approach	Best for	Limitation
AppThemeBinding	Automatic light/dark with OS — minimal code	Only two themes (light + dark)
ResourceDictionary swap	Custom branded themes, more than two themes, user preference	More setup; must use `DynamicResource` everywhere
Both combined	OS-driven response plus custom theme colors	Most flexible but most complex


<Application.Resources>
    <ResourceDictionary>

        
        <Color x:Key="LightPageBackground">#FFFFFF</Color>
        <Color x:Key="DarkPageBackground">#1E1E1E</Color>
        <Color x:Key="LightPrimaryText">#333333</Color>
        <Color x:Key="DarkPrimaryText">#E0E0E0</Color>

        
        <Style TargetType="ContentPage" ApplyToDerivedTypes="True">
            <Setter Property="BackgroundColor"
                    Value="{AppThemeBinding Light={StaticResource LightPageBackground},
                                            Dark={StaticResource DarkPageBackground}}" />
        </Style>

        <Style TargetType="Label">
            <Setter Property="TextColor"
                    Value="{AppThemeBinding Light={StaticResource LightPrimaryText},
                                            Dark={StaticResource DarkPrimaryText}}" />
        </Style>

    </ResourceDictionary>
</Application.Resources>

<Label Text="Themed text"
       TextColor="{AppThemeBinding Light=Green, Dark=Red}"
       BackgroundColor="{AppThemeBinding Light=White, Dark=Black}" />

<Label TextColor="{AppThemeBinding Light={StaticResource LightPrimary},
                                   Dark={StaticResource DarkPrimary}}" />

var label = new Label();

// Color-specific helper
label.SetAppThemeColor(Label.TextColorProperty, Colors.Green, Colors.Red);

// Generic helper — works for any bindable property type, not just Color
label.SetAppTheme<Color>(Label.TextColorProperty, Colors.Green, Colors.Red);
label.SetAppTheme<double>(Label.FontSizeProperty, 14, 16);

// The BindableProperty must belong to the object you call it on —
// Image.SourceProperty goes on an Image, not a Label.
var image = new Image();
image.SetAppTheme<ImageSource>(Image.SourceProperty,
    ImageSource.FromFile("logo_light.png"),
    ImageSource.FromFile("logo_dark.png"));

<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                    x:Class="MyApp.Themes.LightTheme">
    <Color x:Key="PageBackgroundColor">White</Color>
    <Color x:Key="PrimaryTextColor">#333333</Color>
    <Color x:Key="AccentColor">#2196F3</Color>
</ResourceDictionary>

namespace MyApp.Themes;

public partial class LightTheme : ResourceDictionary
{
    public LightTheme() => InitializeComponent();
}

<ContentPage BackgroundColor="{DynamicResource PageBackgroundColor}">
    <Label Text="Hello"
           TextColor="{DynamicResource PrimaryTextColor}" />
    <Button Text="Action"
            BackgroundColor="{DynamicResource AccentColor}" />
</ContentPage>

static ResourceDictionary? _currentTheme;

void ApplyTheme(ResourceDictionary theme)
{
    var merged = Application.Current!.Resources.MergedDictionaries;

    // ✅ Remove ONLY the previous theme — Colors.xaml / Styles.xaml survive
    if (_currentTheme is not null)
        merged.Remove(_currentTheme);

    merged.Add(theme);
    _currentTheme = theme;
}

// Usage
ApplyTheme(new DarkTheme());

// ❌ Destroys the app's Colors.xaml and Styles.xaml along with the old theme
var merged = Application.Current!.Resources.MergedDictionaries;
merged.Clear();
merged.Add(theme);

AppTheme currentTheme = Application.Current!.RequestedTheme;
// Returns AppTheme.Light, AppTheme.Dark, or AppTheme.Unspecified

// Force dark mode regardless of OS setting
Application.Current!.UserAppTheme = AppTheme.Dark;

// Reset to follow system theme
Application.Current!.UserAppTheme = AppTheme.Unspecified;

Application.Current!.RequestedThemeChanged += (s, e) =>
{
    AppTheme newTheme = e.RequestedTheme;
    // Update UI or switch ResourceDictionaries
};

<Label TextColor="{AppThemeBinding
    Light={DynamicResource LightPrimary},
    Dark={DynamicResource DarkPrimary}}" />

Application.Current!.RequestedThemeChanged += (s, e) =>
{
    ApplyTheme(e.RequestedTheme == AppTheme.Dark
        ? new DarkTheme()
        : new LightTheme());
};

// Save choice
Preferences.Set("AppTheme", "Dark");

// Restore on startup (in App constructor or CreateWindow)
var saved = Preferences.Get("AppTheme", "System");
Application.Current!.UserAppTheme = saved switch
{
    "Light" => AppTheme.Light,
    "Dark"  => AppTheme.Dark,
    _       => AppTheme.Unspecified
};

[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 { }


<Label TextColor="{DynamicResource PrimaryTextColor}" />

<Label TextColor="{StaticResource PrimaryTextColor}" />

static ResourceDictionary? _currentTheme;

void ApplyTheme(bool useDark)
{
    var merged = Application.Current!.Resources.MergedDictionaries;

    // Remove only the previous theme — never Clear(), which also wipes
    // the template's Colors.xaml / Styles.xaml
    if (_currentTheme is not null)
        merged.Remove(_currentTheme);

    _currentTheme = useDark ? new DarkTheme() : new LightTheme();
    merged.Add(_currentTheme);
}

// React to the OS switching light/dark
Application.Current!.RequestedThemeChanged += (s, e) =>
    ApplyTheme(e.RequestedTheme == AppTheme.Dark);


<Label TextColor="#333333" />

<Label TextColor="{DynamicResource PrimaryTextColor}" />

Platform	Minimum Version
iOS	13+
Android	10+ (API 29)
macOS Catalyst	10.15+
Windows	10+

maui-theming

Install

Related skills

Questions

.NET MAUI Theming

When to Use

When Not to Use

Inputs

Workflow

Rules That Change the Answer

Choosing an Approach

AppThemeBinding (OS Light/Dark)

Define the palette once — don't scatter literals

XAML (inline form, for one-offs)

C# Extension Methods

ResourceDictionary Theming (Custom Themes)

Step 1 — Define Theme Dictionaries

Step 2 — Consume with DynamicResource

Step 3 — Switch Themes at Runtime

System Theme Detection

Read the Current Theme

Override the System Theme

React to Theme Changes

Combining Both Approaches

Saving and Restoring User Preference

Common Pitfalls

Android: ConfigChanges.UiMode is Required

DynamicResource vs StaticResource

Hardcoded Colors Break Theming

CSS Themes Cannot Be Swapped at Runtime

Theme Keys Must Match Across Dictionaries

Platform Support

Quick Reference