Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: UnoDspImportColors mention #1406

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified doc/assets/material-theme-builder-export2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 30 additions & 6 deletions doc/material-dsp.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,18 +32,42 @@ This package will be automatically present in the project after [creating a new
* 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](assets/material-theme-selection-wizard.png)

## Generating a custom color palette and export as DSP file
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` and `csharp`.

```xml
<ItemGroup>
<UnoDspImportColors Include="Styles\*.json" Generator="csharp" OutputPath="json_file.g.cs" />
</ItemGroup>
```

> [!NOTE]
> The Uno.Sdk will automatically include this configuration for you. Creating a new project with the _CSharpMarkup_ feature will automatically set the generator attribute to _csharp_. It will set the generator to _xaml_ by default.

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

1. Navigate to the [Material Theme Builder](https://m3.material.io/theme-builder#/custom) and select the colors you want to use for your application.
2. Locate the _Export_ button and pick the _material Tokens (DSP)_ format.
2. Locate the _Export_ button and pick the _Material Theme (JSON)_ format.

![Export Button](assets/material-theme-builder-export1.png) ![DSP Selection](assets/material-theme-builder-export2.png)
3. Save the zip file to your computer.
4. Replace the file `ColorPaletteOverride.zip` in the `Styles` folder of your application project with the one you just downloaded.
5. Build your application. The `ColorPaletteOverride.xaml` file will be automatically updated with the colors present in the DSP zip file.
3. Save the file to your computer.
4. Replace the `ColorPaletteOverride.json` file in the `Styles` folder of your application project with the one you just downloaded.
5. 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.zip` file from the `Styles` folder, the file won't get overwritten anymore.
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](https://nuget.org/packages/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, the Uno Figma Plugin still supports this file format.
> To be able 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.