Do I use Light, Dark, Default, or HighContrast when writing ThemeDictionaries?

Question

I've seen lots of different keys used in ThemeDictionaries in UWP/WinUI XAML: Light, Dark, Default, & HighContrast. However, these seem partially redundant.

Which ones should I use?

The docs recommend Light, Dark, and HighContrast:

Specify theme dictionaries for both "Light" and "Dark" in addition to your "HighContrast" dictionary. Although you can create a ResourceDictionary with "Default" as the key, it's preferred to be explicit and instead use "Light", "Dark", and "HighContrast".

But official WinUI controls like DropDownButton use Default, Light, and HighContrast:

<ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
            <StaticResource x:Key="DropDownButtonForegroundSecondary" ResourceKey="TextFillColorSecondaryBrush"/>
            <StaticResource x:Key="DropDownButtonForegroundSecondaryPointerOver" ResourceKey="TextFillColorTertiaryBrush"/>
            <StaticResource x:Key="DropDownButtonForegroundSecondaryPressed" ResourceKey="TextFillColorTertiaryBrush"/>
        </ResourceDictionary>

        <ResourceDictionary x:Key="Light">
            <StaticResource x:Key="DropDownButtonForegroundSecondary" ResourceKey="TextFillColorSecondaryBrush"/>
            <StaticResource x:Key="DropDownButtonForegroundSecondaryPointerOver" ResourceKey="TextFillColorTertiaryBrush"/>
            <StaticResource x:Key="DropDownButtonForegroundSecondaryPressed" ResourceKey="TextFillColorTertiaryBrush"/>
        </ResourceDictionary>

        <ResourceDictionary x:Key="HighContrast">
            <StaticResource x:Key="DropDownButtonForegroundSecondary" ResourceKey="SystemColorButtonTextColorBrush"/>
            <StaticResource x:Key="DropDownButtonForegroundSecondaryPointerOver" ResourceKey="SystemColorHighlightColorBrush"/>
            <StaticResource x:Key="DropDownButtonForegroundSecondaryPressed" ResourceKey="SystemColorHighlightColorBrush"/>
        </ResourceDictionary>
    </ResourceDictionary.ThemeDictionaries>

How do I choose which keys to use?

Answer 1

I'd go with the official Default, Light and HighContrast implementing Default as Dark, which will be applied when the requested theme is not found.