Material Theme

Migration

This section outlines the steps that need to be performed in order to upgrade to the latest version the Telerik and Kendo UI Material theme.

Color

Starting with Telerik and Kendo UI Material theme v8.0.0, there is a new Color System which introduces a new way of implementing and customizing the colors.

To migrate your customizations to the new Color System in the Telerik and Kendo UI Material theme, use either of the following approaches:

• Manual Migration.
• Automated Migration.

It is also possible to postpone the migration by setting the $kendo-enable-color-system variable to false. This will disable the new Color System, therefore nothing will need to be migrated.

Manual Migration

If you have customized some of the old color variables in your application ( $kendo-color-primary, $kendo-body-bg, $kendo-body-text, etc) they will need to be migrated in order for them to take effect in the new Color System.

The table below shows the mapping between the old and the new variables.

The Migration process consists of two steps:

1. Assign your custom color values to the new variables
2. Replace the usage of the old variables with the new ones

Assign your custom color values to the new variables

For the purpose of this guide, lets assume that you have customized the $kendo-color-primary variable so it matches your branding.

In order to migrate it, you would need to provide the values for all 10 variables in the "Primary" variable group:

• primary-subtle
• primary-subtle-hover
• primary-subtle-active
• primary
• primary-hover
• primary-active
• primary-emphasis
• primary-on-subtle
• on-primary
• primary-on-surface

The "Subtle" variables (i.e. primary-subtle) are used for the Solid Chip and its states, for the Card theme colors, for the MessageBox theme colors, in general for elements that need a subtle shade of the main color.

The "Main" variables (i.e. primary) are used for the Solid Button and its states, for selected states in some of the components like List, Scheduler and so on.

The "Emphasis" variable (i.e. primary-emphasis) is used mostly for border color. A good example are the different theme colors of the Solid Chip.

The "On Subtle" variable (i.e. primary-on-subtle) is used for the text color when it is on a "Subtle" background. A good example are the different theme colors of the Solid Chip.

The "On" variable (i.e. on-primary) is used for text color when it is on a "Main" background. A good example is the Solid Button.

The "On-Surface" variable (i.e. primary-on-surface) is used for text color, mostly in the outline fill mode of the components. A good example is the Outline Button.

The k-generate-color-variations() function

Providing 10 different color values might be overwhelming, especially when you had to provide just one color value in the past. That is why we created the k-generate-color-variations() function. It does the same thing that Kendo Themes were doing behind the scenes in the past - creating the different shades of a given color by lightening/darkening it with a given percentage.

The function accepts 3 parameters - k-generate-color-variations(name, color, theme):

• name is the name of the color group that we want to generate the colors for. It is a string value.
• color is the color value. It could be a HEX or RBGA value.
• theme is the theme name we want to generate the colors for. It is a string value and could be one of the following - "default", "classic", "bootstrap", "material" or "fluent".

Having the above in mind, here is how we migrate the $kendo-color-primary variable:

// Old Code
$kendo-color-primary: #9c27b0;

// The old code should be replaced with this code
@import "@progress/kendo-theme-core/scss/functions/index.import.scss";

$kendo-colors: ();
$kendo-colors: k-map-merge($kendo-colors,
k-generate-color-variations( 'primary', #9c27b0, 'material' )
);

And here is a more realistic example where more variables need to be migrated:

// Old Code
$kendo-color-primary: #9c27b0;
$kendo-color-secondary: #e51a5f;
$kendo-color-info: #0058e9;
$kendo-color-success: #37b400;
$kendo-component-bg: #fafafa;
$kendo-component-text: #111111;
$kendo-component-border: rgba(0, 0, 0, 0.2);
$kendo-base-bg: #f3f2f1;
$kendo-body-bg: #f8f8f8;
$kendo-button-bg: #eaeaea;

// The old code should be replaced with this code
@import "@progress/kendo-theme-core/scss/functions/index.import.scss";

$kendo-colors: ();
$kendo-colors: k-map-merge($kendo-colors, (
app-surface: #f8f8f8,
on-app-surface: #111111,
subtle: rgba(0, 0, 0, 0.54),
surface: #f3f2f1,
surface-alt: #fafafa,
border: rgba(0, 0, 0, 0.2),
border-alt: rgba(0, 0, 0, 0.3)
),
k-generate-color-variations( 'primary', #9c27b0, 'material' ),
k-generate-color-variations( 'secondary', #e51a5f, 'material' ),
k-generate-color-variations( 'info', #0058e9, 'material' ),
k-generate-color-variations( 'success', #37b400, 'material' ),
k-generate-color-variations( 'base', #eaeaea, 'material' )
);

Replace the usage of the old variables with the new ones

Once the custom color values are assigned to the new variables, the old variables need to be removed from your codebase. The recommended way of doing this is by using the k-color() function. For more details, please refer to the Predefined Color Variables section above.

Here is an example of how the old variables should be replaced:

// Old code
.my-element {
background-color: $kendo-color-primary;
color: $kendo-color-primary-contrast;
}

.my-element-2 {
background-color: $kendo-component-bg;
color: $kendo-component-text;
border-color: $kendo-component-border;
}

.my-element-3:hover {
background-color: $kendo-hover-bg;
}

// The old code should be replaced with this code
.my-element {
background-color: k-color( primary );
color: k-color( on-primary );
}

.my-element-2 {
background-color: k-color( surface-alt );
color: k-color( on-app-surface );
border-color: k-color( border );
}

.my-element-3:hover {
background-color: k-color( base-hover );
}

Automated Migration

We also created a BASH script that automates the above steps.

The Colors Migrator script can be downloaded from the Kendo Themes repository on Github. It checks all SCSS files in a given directory for "old" color variables and migrates them for the new Color System:

bash colors-migrator.sh source_directory --theme theme_name --functionality

The script has two functionalities, controlled with a flag, that must be executed in a specific order, otherwise the migration will not be successful and will lead to a broken codebase.

First, the script must be executed with the --migrate_color_values functionality/flag:

bash colors-migrator.sh app/styles --theme material --migrate_color_values

The above command tells the Colors Migrator script that the Kendo Material theme should be migrated. It will look in all SCSS files in the app/styles directory and will migrate the color customizations for the new Kendo Color System - it will take the custom color values and will assign them to the new variables.

Once the above is done, the script must be executed again, this time with the --migrate_variable_usage functionality/flag:

bash colors-migrator.sh app/styles --theme material --migrate_variable_usage

This will migrate the usage of the old variables with the new ones.