[Spec] Scoped Color Overrides

[kazo0]

The Problem

An application may be designed around a common theme of colors for branding and other purposes but may still have a need to include a set of custom colors that are used in specific part of an application. For example, an e-commerce app may have a primary color of Blue for its branding so, implicitly, all themed components will follow that color theme of using Blue as its primary color. However, something like the Checkout page may require some components like a "Pay Now" button to be themed as though the primary color were Green instead of Blue. This could initially be achieved by simply setting the Background of the specific button to Green but then we run into issues where certain brushes used for the visual states of the button may still use the original Blue primary brush as its source and leads to visual issues. There can also be problems with legibility if the Foreground color of the button contrasts well with the default primary color but not with this new custom Background color that you may want to use. Currently, this would require a new style to be created in order to re-template the component and use alternative colors for the visual states.

Intermediate Solution (Lightweight Styling)

How this would be solved currently in WinUI would be to utilize Lightweight Styling. The styles within Themes and Toolkit support, or will soon support, Lightweight Styling and define specific resource keys that can be overridden in order to customize how a component looks in all visual states. This, however, is a very verbose and cumbersome method of customization. In the case of our example e-commerce application, we would need to redefine each of the Background and Foreground resources for each visual state that we want to support. An example usage for Lightweight Styling would look something like:

<Button Content="Pay Now"
        Style="{StaticResource FilledButtonStyle}">
        <Button.Resources>
            <SolidColorBrush x:Key="FilledButtonBackground" Color="Green" />
            <SolidColorBrush x:Key="FilledButtonBackgroundPointerOver" Color="LightGreen" />
            <SolidColorBrush x:Key="FilledButtonBackgroundPressed" Color="DarkGreen" />
            <SolidColorBrush x:Key="FilledButtonForeground" Color="White" />
            <SolidColorBrush x:Key="FilledButtonForegroundPointerOver" Color="White" />
            <SolidColorBrush x:Key="FilledButtonForegroundPressed" Color="White" />
        </Button.Resources>
</Button>

Proposed Solution (Scoped Color Overrides)

It would be beneficial to be able to declare certain "color sets" that can be generated around specific "seed" colors and we could then specify which color set a specific component or page should use when resolving the color theme resources. We could then create a custom set of colors, keyed as something like "PayNow" where Green was the PrimaryColor and White would be the OnPrimaryColor. The resulting XAML could then look something like

xmlns:themes="Uno.Themes"

...

<Button Content="Pay Now"
        Style="{StaticResource FilledButtonStyle}"
        themes:ThemeExtensions.ColorSet="PayNow" />

The color sets would be declared within the bootstrapping of the current theme. Taking the current MaterialTheme as an example inside of the AppResources.xaml, we could "register" they key color sets like so:

xmlns:um="Uno.Material"

...

<um:MaterialTheme>
    <um:MaterialTheme.ColorSetDictionaries>
        <ResourceDictionary x:Key="PayNow">
            <Color x:Key="PrimaryColor">Green</Color>
            <Color x:Key="OnPrimaryColor">White</Color>
            ....
        </ResourceDictionary>
    </um:MaterialTheme.ColorSetDictionaries>
</um:MaterialTheme>

We would essentially allow people to be defining multiple ColorPaletteOverrides and we would handle the work of re-initializing the Brushes based on the provided "color set" (override palette) within the context of the control that has the ColorSet property declared.

Seeding

Going a step further, we could introduce the ability to simply provide an initial seed color for the custom color sets and have the rest of the override palette generated at build time based on that color. We would have it work similar to the way you use the Material Theme Builder

So the MaterialTheme bootstrapping of color sets could be simplified even further and look something like:

xmlns:um="Uno.Material"

...

<um:MaterialTheme>
    <um:MaterialTheme.ColorSets>
        <ColorSet x:Key="PayNow" Seed="Green" />
    </um:MaterialTheme.ColorSets>
</um:MaterialTheme>

In this case we would define custom ResourceDictionaries called ColorSet that would accept a Seed and use the algorithms from the theme builders to generate the appropriate colors.

Questions

1. Are we better off splitting up everything into "color sets" or is it acceptable to just re-init the entire set of color/brush resources for each custom color dictionary? To avoid complexity of having to break everything out into individual sets, we could instead basically extract this logic from the theme init and re-run it for each declared custom color set in the AppResources.xaml and reference them in the Resources of whatever control is using a custom ColorSet key. We may be creating more StaticResources than needed at times but its much simpler to do. Is the performance going to take to much of a hit on startup @jeromelaban?
2. I feel the "seed" part is not necessarily needed for an MVP, as long as someone can define multiple color palette overrides and be able to use them in whatever scope they want, this is a win. Thoughts?
3. What does the API look like for this attached property/behavior that we are going to need? Something like ThemeExtensions.ColorSet="PayNow" is fine?
4. What does the API look like for the theme init color set stuff? MaterialTheme.ColorSetDictionaries, I figured follow suit with ResourceDictionaries.MergedDictionaries and ResourceDictionaries.ThemeDictionaries

[jeanplevesque]

With the current inability of scoping color overrides into styles for easy reuse, this seems like a primordial feature.

[eriklimakc]

So, for now we named the class as MaterialBrush that can re-initialize the brushes with the new ResourceDictionary provided.

Control level

Page level

@kazo0 @francoistanguay

[kazo0]

Maybe a way forward would be to try to achieve something similar to the ColorPaletteResources class.

Where MaterialBrushes has a separate property for each independent color that maps to multiple brushes. So we'd have something like <MaterialBrushes Primary="Red" Surface="Black" OnSurface="White" .... /> and the MaterialBrushes class would only initialize the Brush resources for the color properties that were explicitly set. In this way we wouldn't really need the idea of Color Sets

[francoistanguay]

Is it specific to Material or could it have a name without Material in it?

Regardless of the name, are we agreeing that the ultimate api would be something like ?

We can discuss if it's Theme.Color, RequestedColor, ColorKey, ColorSet?

In all cases, I care more about usage and the outer API name than I care about the MaterialBrushers/ColorOverrideSource kind of naming that ultimately would be "internal"oran implementation detail.

Am also wondering if ColorOverrideSource is the right name in the context of Brusher...Is it really an override or just a "Source"? Put otherwise, do we need to set colors and override while bootstrapping the app or can we just "specify" the colors on the brushers the first time we init as well?

[kazo0]

Is it specific to Material or could it have a name without Material in it?

For now these are all Material-related until we have an actual Uno.Themes library that is shared across multiple design systems. Since the semantic styles and brushes and resources came from Uno.Material originally, nothing has been pulled up to a design-agnostic library yet as we have no other design system library using these resources yet, apart from Material itself.

Regardless of the name, are we agreeing that the ultimate api would be something like ?

We can discuss if it's Theme.Color, RequestedColor, ColorKey, ColorSet?

In all cases, I care more about usage and the outer API name than I care about the MaterialBrushers/ColorOverrideSource kind of naming that ultimately would be "internal"oran implementation detail.

Am also wondering if ColorOverrideSource is the right name in the context of Brusher...Is it really an override or just a "Source"? Put otherwise, do we need to set colors and override while bootstrapping the app or can we just "specify" the colors on the brushers the first time we init as well?

So after discussing more with @eriklimakc, I'm not sure creating keyed "color sets" and defining them in the MaterialTheme initialization process in App.xaml makes the most sense. If people are going to have multiple sets of color palettes that they want to reuse, they would create multiple ResourceDictionary files in the project. So they could have a PayNowColorPalette.xaml, a RedPrimaryColorPalette.xaml, etc. and then they could use our proposed ThemeExtensions to do something like:

xmlns:um="Uno.Material"

...

<Button Content="Pay Now"
        Style="{StaticResource FilledButtonStyle}"
        um:ThemeExtensions.ColorPaletteSource="ms-appx:///MyApp/PayNowColorPalette.xaml" />

Or inline it with

xmlns:um="Uno.Material"

...

<Button Content="Pay Now"
        Style="{StaticResource FilledButtonStyle}">
	<um:ThemeExtensions.ColorPalette>
		<ResouceDictionary>
			<Color x:Key="PrimaryColor">Red</Color>
		</ResourceDictionary>
	</um:ThemeExtensions.ColorPalette>
</Button

The ThemeExtensions would, in effect, just initialize MaterialBrushes internally and set the ColorOverride to the ResourceDictionary provided by the ThemeExtensions.ColorPalette property.

The next step would be to only re-init the Brushes that are affected by what is defined in the custom color palettes. The only way I see that working is by maintaining some sort of mapping of the Color keys to their respective set of Brushes. So when MaterialBrushes is given a ResourceDictionary for the color palette, we can read the keys in the dictionary and determine which colors are being set and then load only the sets of Brushes that correspond to those specific colors.

For example, with a ColoPalette that looks something like:

<ResourceDictionary>
	<ResourceDictionary.ThemeDictionaries>
		<ResourceDictionary x:Key="Light">
			<Color x:Key="PrimaryColor">Red</Color>
			<Color x:Key="SurfaceColor">White</Color>
		</ResourceDictionary>
		<ResourceDictionary x:Key="Dark">
			<Color x:Key="PrimaryColor">Orange</Color>
			<Color x:Key="SurfaceColor">Black</Color>
		</ResourceDictionary>
	</ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

We could detect that only "SurfaceColor" and "PrimaryColor" are being set and use our mapping to determine that we only need to re-init the following Brushes:

<!--#region PrimaryColor -->
<SolidColorBrush x:Key="PrimaryBrush" Color="{StaticResource PrimaryColor}" />
<SolidColorBrush x:Key="PrimaryHoverBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource HoverOpacity}" />
<SolidColorBrush x:Key="PrimaryFocusedBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource FocusedOpacity}" />
<SolidColorBrush x:Key="PrimaryPressedBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource PressedOpacity}" />
<SolidColorBrush x:Key="PrimaryDraggedBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource DraggedOpacity}" />
<SolidColorBrush x:Key="PrimarySelectedBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource SelectedOpacity}" />
<SolidColorBrush x:Key="PrimaryMediumBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource MediumOpacity}" />
<SolidColorBrush x:Key="PrimaryLowBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource LowOpacity}" />
<SolidColorBrush x:Key="PrimaryDisabledBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource DisabledOpacity}" />
<SolidColorBrush x:Key="PrimaryDisabledLowBrush" Color="{StaticResource PrimaryColor}" Opacity="{StaticResource DisabledLowOpacity}" />

<!--#region SurfaceColor -->
<SolidColorBrush x:Key="SurfaceBrush" Color="{StaticResource SurfaceColor}" />
<SolidColorBrush x:Key="SurfaceHoverBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource HoverOpacity}" />
<SolidColorBrush x:Key="SurfaceFocusedBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource FocusedOpacity}" />
<SolidColorBrush x:Key="SurfacePressedBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource PressedOpacity}" />
<SolidColorBrush x:Key="SurfaceDraggedBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource DraggedOpacity}" />
<SolidColorBrush x:Key="SurfaceSelectedBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource SelectedOpacity}" />
<SolidColorBrush x:Key="SurfaceMediumBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource MediumOpacity}" />
<SolidColorBrush x:Key="SurfaceLowBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource LowOpacity}" />
<SolidColorBrush x:Key="SurfaceDisabledBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource DisabledOpacity}" />
<SolidColorBrush x:Key="SurfaceDisabledLowBrush" Color="{StaticResource SurfaceColor}" Opacity="{StaticResource DisabledLowOpacity}" />

Another way would be to split all of these brush groups into individual resource dictionaries internally and then simply load each one accordingly.

[kazo0]

fyi @francoistanguay / @jeromelaban ^

[francoistanguay]

I have so many questions. Requires a call.

Needs to work with XAML and C#.
Needs to think on how typically colors would be exported in DSP...It's a bunch of colors, including Primary/Secondary and then Customs.... So if needs to be split one color per file, needs to be figured out.
I dont think Custom colors should be treated differently from primary/Secondary.
Need to figure out if we call a Color Set a ColorPalette or if a ColorPalette is really the combination of all colors (Primary, Secondary, Custom colors, ...)... This is just naming.

If we dont need to instantiate the RD for Colors onceand then reference it by key (because it needs to be duplicated locally somehow), then maybe we could still have a logical alias/key name instead of relying on the ms-appx file name (especially because of C# Markup considerations)