Using the DSP Tooling in Uno.Material

Introduction

Is it possible to automate the creation of the Material Design color palette? Yes, it is. Uno.Material provides a tooling to generate the color palette from the official Material Design color palette. This tooling is available in the Uno.Dsp.Cli and Uno.Dsp.Tasks NuGet packages. The following instructions will cover the Uno.Dsp.Tasks version, which is more automatic.

Note

Make sure you are referencing the generated XAML file in your application's App.xaml file, as shown in the following example:

 <MaterialTheme xmlns="using:Uno.Material"
                ColorOverrideSource="ms-appx:///PROJECT_NAME/Styles/Application/MaterialColorsOverride.xaml" />

More details In the Manual Color Overrides section of the Getting Started page

The Uno.Dsp.Tasks NuGet package

This package will be automatically present in the project after creating a new Uno Platform project specifying the Material theme. It is also possible to add it manually to an existing Uno Platform project by adding the following line to the PackageReference section of the csproj file:

  • Add a nuget package reference:

    <PackageReference Include="Uno.Dsp.Tasks" Version="[latest version]" />

  • The package is already present when you select Material theme during project creation: Selection of Material theme when creating a project using the Uno Template Wizard

It is possible to configure the import process. The UnoDspImportColors item found in the csproj file has a number of attributes we can set:

Attribute Description Default Value
Include Style files to input
Generator* Type of generator to use Xaml
OutputPath** Path to use for the output Input file directory

* The possible values for Generator are Xaml or Csharp.

** If Include is a glob (eg: *.json), OutputPath should be a directory.

<ItemGroup>
   <UnoDspImportColors Include="Styles\*.json" Generator="Csharp" OutputPath="Styles\Theme\"  />
</ItemGroup>

Generating a custom color palette and exporting it as a JSON file

  1. Navigate to the Material Theme Builder and select the colors you want to use for your application.

  2. When you are done customizing, open the Export section located at the top rightmost of the screen.

    material-theme-export-section

  3. In the Export section, locate the Export button and pick the Material Theme (JSON) format.

    material-theme-export-button material-theme-export-json

  4. Save the file to your computer.

  5. Replace the ColorPaletteOverride.json file in the Styles folder of your application project with the one you just downloaded.

  6. Build your application. The ColorPaletteOverride.xaml file will be automatically updated with the colors present in the JSON file.

More flexibility

This will generate the file at each build, potentially overriding any changes you made to the file. If you want to keep it that way, you can simply remove the ColorPaletteOverride.json file from the Styles folder, the file won't get overwritten anymore.

Alternatively, you can also use the Uno.Dsp.Cli package to generate the file from the command line. This will allow you to generate the file only when you want to, and not at each build.

Note

Although the Material Theme Builder Tool doesn't export Material Tokens (DSP) packages anymore, to import DSP packages just follow the same steps described previously and save the downloaded DSP zip file as ColorPaletteOverride.zip in the Styles folder of your application project. In that case, make sure to delete the material-theme.json file from Styles folder before building your application, to avoid conflicts.