WinUI Styling and Theming

This document covers the fundamental concepts of styling and theming within the Windows UI Library (WinUI). Proper styling ensures your application is visually appealing, consistent with the Windows design language, and accessible to all users.

Understanding Resource Dictionaries

WinUI leverages XAML Resource Dictionaries extensively for defining styles, templates, colors, and other reusable assets. These dictionaries allow for centralized management of your application's visual properties.

Global vs. Local Resource Dictionaries

Resource dictionaries can be defined at various scopes:

• App.xaml: Resources defined here are available application-wide.
• Page/UserControl Level: Resources specific to a particular page or control.
• Control Level: Resources within a control's template.

Key Styling Concepts

Styles

A Style targets a specific control type and defines its default appearance and behavior. You can define properties like FontSize, Foreground, Background, and even override entire control templates.

<Page.Resources>
    <Style TargetType="Button" x:Key="PrimaryButtonStyle">
        <Setter Property="Background" Value="{ThemeResource SystemAccentColor}" />
        <Setter Property="Foreground" Value="White" />
        <Setter Property="Padding" Value="12,6"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="HorizontalAlignment" Value="Left"/>
        <Setter Property="Template">
            <ControlTemplate TargetType="Button">
                <Border Background="{TemplateBinding Background}"
                        BorderBrush="{TemplateBinding BorderBrush}"
                        BorderThickness="{TemplateBinding BorderThickness}"
                        CornerRadius="4"
                        Padding="{TemplateBinding Padding}">
                    <ContentPresenter HorizontalAlignment="Center" VerticalAlignment="Center" />
                </Border>
            </ControlTemplate>
        </Setter>
    </Style>
</Page.Resources>

<Button Style="{StaticResource PrimaryButtonStyle}" Content="Click Me" />

Templates

Control templates define the visual structure of a control. They are composed of XAML elements like Grid, Border, TextBlock, etc., and use binding to connect to the control's properties.

Theme Resources

WinUI provides built-in theme resources that adapt to user preferences (e.g., light/dark mode, high contrast). These are accessed using the ThemeResource markup extension.

<TextBlock Text="Hello, WinUI!"
               Foreground="{ThemeResource TextColor}"
               FontSize="18" />

<Button Content="Action"
        Background="{ThemeResource SystemAccentColor}"
        Foreground="White" />

Common Theme Resources include:

• SystemAccentColor
• TextPrimaryColor, TextSecondaryColor, TextDisabledColor
• ControlFillColorDefault, ControlFillColorPressed
• BackgroundThemeBrush

Applying Styles

Styles can be applied:

• Explicitly using the Style property of a control.
• Implicitly by defining a style without a x:Key, which applies to all instances of the targeted element type within the scope.

Customizing Theme Resources

You can override default theme resources in your App.xaml to globally change colors or other theme-dependent properties.

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <ResourceDictionary Source="ms-appx:///MyCustomStyles.xaml" />
        </ResourceDictionary.MergedDictionaries>

        <!-- Override a specific theme resource -->
        <SolidColorBrush x:Key="{ThemeResource SystemAccentColor}" Color="Purple" />
    </ResourceDictionary>
</Application.Resources>

Layout Styling

While not strictly "styling" in terms of appearance, layout plays a crucial role. WinUI offers powerful layout panels like Grid, StackPanel, and RelativePanel. Styles can also influence layout properties.

Interactive Elements and Styling

WinUI controls are designed with state-aware styling. For example, buttons have different visual states for Normal, PointerOver, Pressed, and Disabled.

Best Practices

• Use ThemeResource for colors and resources that should adapt to system settings.
• Centralize reusable styles and templates in ResourceDictionary files.
• Apply styles consistently across your application.
• Leverage implicit styles for common controls to reduce XAML verbosity.
• Test your application in both light and dark themes.

By mastering WinUI styling, you can create applications that are not only functional but also beautiful and engaging for your users.