C# implementation of Google's Material Color Utilities
Includes all of the algorithms you might need for adding Material You colors to your .NET app:
- .NET MAUI: add beautiful Material You dynamic theming to your .NET MAUI app in just a single line of code
- HCT: a new color space designed by Google for perfect contrasts, properties: Hue, Chroma and Tone
- Palettes: a
TonalPalette
allows easy access to the tones of a color, aCorePalette
contains the 6 key tonal palettes: Primary, Secondary, Tertiary, Neutral, NeutralVariant and Error - Scheme: map the colors in a Core Palette to roles, like
Primary
,TertiaryContainer
orOnError
- Quantize: reduce the number of unique colors in an image to just 128
- Score: order those colors based on suitability for theming
- Blend: shift a color towards the theme hue
- Extension: add custom colors, override mappings
Other stuff:
Get the packages from Nuget:
Package | Description | Link |
---|---|---|
MaterialColorUtilites |
Contains all of the color algorithms and helpers | |
MaterialColorUtilites.Maui |
Adds dynamic colors to your .NET MAUI app |
Adding beautiful Material You dynamic colors to your app is super simple, just follow these instructions. The library will handle everything else.
Light/dark mode handling works everywhere, but the accent color is different on all of the platforms:
- Android ≥12.0 (API 31): use system colors
- Android ≥8.1 (API 27): use WallpaperColors.Primary as seed color
- Android ≥7.0 (API 24): if the
StorageRead
permission has been granted, extract a color from the wallpaper, otherwise use fallback seed - Android ≥5.0 (API 21): use fallback seed
- iOS: no accent color, use fallback seed
- Mac: use accent color
- Windows: use accent color
- Add the
MaterialColorUtilites.Maui
package using the link above - Add the the highlighted lines to your
MauiProgram.cs
+using MaterialColorUtilities.Maui;
namespace YourBeautifulApp;
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
MauiAppBuilder builder = MauiApp
.CreateBuilder()
+ .UseMaterialDynamicColors()
.UseMauiApp<App>();
return builder.Build();
}
}
- (optional) Add placeholders to your
App.xaml
for suggestions when writing XAML
<?xml version = "1.0" encoding = "UTF-8" ?>
<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:local="clr-namespace:YourBeautifulApp"
x:Class="YourBeautifulApp.App">
<Application.Resources>
+ <Color x:Key="Primary" />
+ <Color x:Key="PrimaryContainer" />
+ <Color x:Key="Secondary" />
+ <Color x:Key="SecondaryContainer" />
+ <Color x:Key="Tertiary" />
+ <Color x:Key="TertiaryContainer" />
+ <Color x:Key="Surface" />
+ <Color x:Key="SurfaceVariant" />
+ <Color x:Key="Background" />
+ <Color x:Key="Error" />
+ <Color x:Key="ErrorContainer" />
+ <Color x:Key="OnPrimary" />
+ <Color x:Key="OnPrimaryContainer" />
+ <Color x:Key="OnSecondary" />
+ <Color x:Key="OnSecondaryContainer" />
+ <Color x:Key="OnTertiary" />
+ <Color x:Key="OnTertiaryContainer" />
+ <Color x:Key="OnSurface" />
+ <Color x:Key="OnSurfaceVariant" />
+ <Color x:Key="OnError" />
+ <Color x:Key="OnErrorContainer" />
+ <Color x:Key="OnBackground" />
+ <Color x:Key="Outline" />
+ <Color x:Key="Shadow" />
+ <Color x:Key="InverseSurface" />
+ <Color x:Key="InverseOnSurface" />
+ <Color x:Key="InversePrimary" />
+ <Color x:Key="Surface1" />
+ <Color x:Key="Surface2" />
+ <Color x:Key="Surface3" />
+ <Color x:Key="Surface4" />
+ <Color x:Key="Surface5" />
+ <SolidColorBrush x:Key="PrimaryBrush" />
+ <SolidColorBrush x:Key="PrimaryContainerBrush" />
+ <SolidColorBrush x:Key="SecondaryBrush" />
+ <SolidColorBrush x:Key="SecondaryContainerBrush" />
+ <SolidColorBrush x:Key="TertiaryBrush" />
+ <SolidColorBrush x:Key="TertiaryContainerBrush" />
+ <SolidColorBrush x:Key="SurfaceBrush" />
+ <SolidColorBrush x:Key="SurfaceVariantBrush" />
+ <SolidColorBrush x:Key="BackgroundBrush" />
+ <SolidColorBrush x:Key="ErrorBrush" />
+ <SolidColorBrush x:Key="ErrorContainerBrush" />
+ <SolidColorBrush x:Key="OnPrimaryBrush" />
+ <SolidColorBrush x:Key="OnPrimaryContainerBrush" />
+ <SolidColorBrush x:Key="OnSecondaryBrush" />
+ <SolidColorBrush x:Key="OnSecondaryContainerBrush" />
+ <SolidColorBrush x:Key="OnTertiaryBrush" />
+ <SolidColorBrush x:Key="OnTertiaryContainerBrush" />
+ <SolidColorBrush x:Key="OnSurfaceBrush" />
+ <SolidColorBrush x:Key="OnSurfaceVariantBrush" />
+ <SolidColorBrush x:Key="OnErrorBrush" />
+ <SolidColorBrush x:Key="OnErrorContainerBrush" />
+ <SolidColorBrush x:Key="OnBackgroundBrush" />
+ <SolidColorBrush x:Key="OutlineBrush" />
+ <SolidColorBrush x:Key="ShadowBrush" />
+ <SolidColorBrush x:Key="InverseSurfaceBrush" />
+ <SolidColorBrush x:Key="InverseOnSurfaceBrush" />
+ <SolidColorBrush x:Key="InversePrimaryBrush" />
+ <SolidColorBrush x:Key="Surface1Brush" />
+ <SolidColorBrush x:Key="Surface2Brush" />
+ <SolidColorBrush x:Key="Surface3Brush" />
+ <SolidColorBrush x:Key="Surface4Brush" />
+ <SolidColorBrush x:Key="Surface5Brush" />
</Application.Resources>
</Application>
You can specify the fallback seed as an argument to the extension method or use a lambda for more options:
.UseMaterialDynamicColors(options =>
{
options.FallbackSeed = 0xFFB000B5;
options.UseDynamicColor = false;
})
- In XAML:
<Button Color="{DynamicResource Primary}" />
- In C# views:
Button button = new();
button.SetDynamicResource(Button.BackgroundColorProperty, MaterialColorUtilities.Schemes.Keys.Primary);
- You can also resolve
DynamicColorService
from the MAUI dependency injection container:
using MaterialColorUtilites.Maui;
public class MyService
{
public MyService(DynamicColorService dynamicColorService)
{
Scheme<Color> scheme = dynamicColorService.SchemeMaui;
}
}
For samples check out the Playground.Maui project.
Using custom components (like CorePalette, schemes and mappers) is supported. Just subclass DynamicColorService
and supply your own types as generic arguments.
public class MyDynamicColorService : DynamicColorService<MyCorePalette, MyScheme<int>, MyScheme<Color>, MyLightSchemeMapper, MyDarkSchemeMapper>
{
// You can also override Initialize() and Apply() for custom logic
}
Then use it using the generic extension method:
.UseMaterialDynamicColors<MyDynamicColorService>()
Google's new color space designed for meeting contrast standards easy. Properties:
- Hue: 0-360, the color, like red, orange, yellow, green, blue or violet
- Chroma: how colorful the color is. 0 is gray, and the maximum depends on Hue and Tone.
- Tone: lightness, 0-100, 0 is black, 100 is white
Convert an RGB color to HCT, change its Tone, then convert back:
int argb = Colors.Azure.ToInt();
Hct hct = Hct.FromInt(argb);
hct.Tone = 30;
int tone30 = hct.ToInt();
Check out the Blazor playground running live here or Material Theme Builder for visualisations.
Used for retrieving tones of a color.
// Does the same as the above code
TonalPalette palette = TonalPalette.FromInt(argb);
int tone30 = palette[30];
Contains the Tonal palettes of the key colors. Properties:
public TonalPalette Primary { get; set; }
public TonalPalette Secondary { get; set; }
public TonalPalette Tertiary { get; set; }
public TonalPalette Neutral { get; set; }
public TonalPalette NeutralVariant { get; set; }
public TonalPalette Error { get; set; }
Check out the source code if you want to know how they get constructed.
Scheme
s store the Material Design 3 color role values.
public class Scheme<TColor>
{
public TColor Primary { get; set; }
public TColor OnPrimary { get; set; }
public TColor PrimaryContainer { get; set; }
public TColor OnPrimaryContainer { get; set; }
public TColor Secondary { get; set; }
public TColor OnSecondary { get; set; }
public TColor SecondaryContainer { get; set; }
...
}
Scheme
s are generic so you can use whatever color model you want.
This library uses "mappers" to turn ColorPalette
s into Scheme
s.
int seed = 0xFF5D5FDB;
// Construct a CorePalette
CorePalette corePalette = CorePalette.Of(seed);
// Get a mapper
DarkSchemeMapper mapper = new();
// Map
Scheme<int> scheme = mapper.Map(corePalette);
// Convert color type
Scheme<Color> schemeMaui = scheme.Convert(Color.FromInt);
Scheme<string> schemeString = scheme.Convert(x => "#" + x.ToString("X")[2..]);
For custom colors, roles or mapping check out Extension.
Reduce the number of unique colors in an image. Multiple algorithms are available and they are used together.
Order colors returned by quantization based on suitability for theming and remove similar ones.
Shift a color towards the hue of the seed color.
using MaterialColorUtilities.Blend;
int harmonized = Blender.Harmonize(color, seedColor);
Generate a seed color from an image (e.g. the user's wallpaper):
// Load the image into an int[].
// The image is stored in a resource embedded in the assembly, and then decoded and resized using SkiaSharp.
string imageResourceId = "MaterialColorUtilities.Console.Resources.wallpaper.webp";
using Stream resourceStream = Assembly.GetExecutingAssembly().GetManifestResourceStream(imageResourceId);
SKBitmap bitmap = SKBitmap.Decode(resourceStream).Resize(new SKImageInfo(112, 112), SKFilterQuality.Medium);
int[] pixels = bitmap.Pixels.Select(p => (int)(uint)p).ToArray();
// Run quantization and scoring and use the best color
int seedColor = ImageUtils.ColorsFromImage(pixels).First();
Use that color to create a CorePalette
;
CorePalette corePalette = new(seedColor);
int color = corePalette.Secondary[69];
Turn the CorePalette
into a Scheme<int>
using a mapper:
Scheme<int> lightScheme = new LightSchemeMapper().Map(corePalette);
Scheme<int> darkScheme = new DarkSchemeMapper().Map(corePalette);
Then convert your scheme to one with a different color type:
using Color = System.Drawing.Color;
Scheme<Color> lightSchemeColor = lightScheme.ConvertTo(Color.FromArgb);
Scheme<string> lightSchemeString = lightScheme.ConvertTo(x => "#" + x.ToString("X")[2..]);
The same code can be found in the Playground.Console project.
Adding custom colors
- Define a custom key color if you need by subclassing
CorePalette
:
public class MyCorePalette : CorePalette
{
public TonalPalette Orange { get; set; }
public MyCorePalette(int seed) : base(seed)
{
// You can harmonize a color to make it closer to the seed color
int harmonizedOrange = Blender.Harmonize(0xFFA500, seed);
Orange = TonalPalette.FromInt(harmonizedOrange);
}
}
- Subclass
Scheme<TColor>
public partial class MyScheme<TColor> : Scheme<TColor>
{
public TColor Orange { get; set; }
public TColor OnOrange { get; set; }
public TColor OrangeContainer { get; set; }
public TColor OnOrangeContainer { get; set; }
}
A source generator will generate new converter methods automatically.
Make sure to mark the class
partial
and don't nest it inside another class.If you get warning
CS8032: An instance of analyzer MaterialColorUtilities.Schemes.SchemeConverterGenerator cannot be created...
your IDE/compiler doesn't have Rosyln 4.0, so the source generator won't work. Make sure you are using Visual Studio 2022, MSBuild 17 or .NET 6.
- Create mappers
public class MyLightSchemeMapper : LightSchemeMapper<MyCorePalette, MyScheme<int>>
{
protected override void MapCore(MyCorePalette palette, MyScheme<int> scheme)
{
base.MapCore(palette, scheme);
scheme.Orange = palette.Orange[40];
scheme.OnOrange = palette.Orange[100];
scheme.OrangeContainer = palette.Orange[90];
scheme.OnOrangeContainer = palette.Orange[10];
// You can also override already mapped colors
scheme.Surface = palette.Neutral[100];
}
}
public class MyDarkSchemeMapper : DarkSchemeMapper<MyCorePalette, MyScheme<int>>
{
protected override void MapCore(MyCorePalette palette, MyScheme<int> scheme)
{
base.MapCore(palette, scheme);
scheme.Orange = palette.Orange[80];
scheme.OnOrange = palette.Orange[20];
scheme.OrangeContainer = palette.Orange[30];
scheme.OnOrangeContainer = palette.Orange[90];
}
}
- Use your awesome new code
MyCorePalette myCorePalette = new(seedColor);
MyScheme<string> myDarkScheme = new MyDarkSchemeMapper()
.Map(myCorePalette)
.ConvertTo(StringUtils.HexFromArgb);
The same code can be found in the Playground.Console project.
For more info and samples check out the source code and the playground projects. If you have questions use the Discussions tab.
- Blazor sample (Playground.Wasm project) on the web
- Useful for comparing color spaces and checking HCT color values
- Material Theme Builder
- For creating nice themes
If you have found a bug or need a new feature, go ahead and open an issue.