v8.0.0

New Color System

This article provides a migration guide that lets you move theme customizations applied to theme versions before v8.0.0 to theme v8.0.0.

If you have customized the color variables in any of the Telerik and Kendo UI themes versions prior to v8.0.0 and want to keep these customizations when using a Telerik and Kendo UI themes v8.0.0, you must migrate them to the new Color System. The possible migration scenarios are:

• Using automated migration.
• Using manual migration.
• Using backward compatibility.

In the context of the Telerik and Kendo UI themes, migration refers to the process of moving incompatible customizations to the latest version of the Telerik and Kendo UI themes. Customizations that you apply to a previous version of the Telerik and Kendo UI themes may become incompatible with the latest version of the themes due to breaking changes. Such changes are occasionally required to keep the themes efficient, to phase out deprecated elements, and to enable future development and maintenance.

Automated Migration

The Colors Migrator script is available in the Kendo Themes repository on GitHub. It checks all SCSS files in a given directory for the color variables used in previous theme versions and migrates them to 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:

1. Execute the script with the --migrate_color_values flag. This flag instructs the Colors Migrator script to migrate the Kendo theme. It looks into all SCSS files in the app/styles directory and migrates the color customizations to the new Color System by taking the custom color values and assigning them to the new variables.

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

2. Еxecute the script again but this time using the --migrate_variable_usage flag. This flag instructs the script to migrate the usage of the previous variables.

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

Manual Migration

As an alternative to using the BASH script, you can migrate any customized Sass color variables manually (for example, $kendo-color-primary, $kendo-body-bg, $kendo-body-text, and so on). The manual migration process involves two steps:

1. Assign your custom color values to the new $kendo-colors map.
2. Edit your CSS code and replace the Sass variables used prior to themes v8.0.0 with the new color keys from the $kendo-colors map.

Color Mapping

See the mapping for each theme between the Sass variables used prior to v8.0.0 and the new Sass map (used in v8.0.0 and later). This will help you understand for which of the keys you need to provide values in the $kendo-colors map in order to migrate your custom color values to the new Color System.

• Color Mapping for Telerik and Kendo UI Default Theme
• Color Mapping for Telerik and Kendo UI Bootstrap Theme
• Color Mapping for Telerik and Kendo UI Material Theme
• Color Mapping for Telerik and Kendo UI Fluent Theme
• Color Mapping for Telerik and Kendo UI Classic Theme

Assigning Colors

To migrate a color variable to the new $kendo-colors map, use the k-generate-color-variations(name, color, theme) function that is part of the @progress/kendo-theme-core package. Learn more about the k-generate-color-variations function and its parameters in the Customizing Color Sass Variables section of each theme.

For example, assume you have customized the $kendo-color-primary variable and you must migrate it:

1. The starting point is a code sample with the previously customized variables:

   // Old code (used with theme versions before v8.0.0):
   $kendo-color-primary: #9c27b0;
   
   @import '@progress/kendo-theme-default/dist/all.scss';

2. The code required to replace the previously customized variables with the migrated variables looks like this:

   // New code (used with theme version v8.0.0):
   
   // Using the 'k-generate-color-variations' function to migrate the customized 'primary' color:
   @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, 'default')
   );
   
   // Import a theme (for example, the default theme).
   @import '@progress/kendo-theme-default/dist/all.scss';

The next example is more complex and shows how to migrate multiple customized variables:

1. The starting point is a code sample with the previously customized variables:

   // Old code (used with theme versions before v8.0.0):
   $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;
   
   @import '@progress/kendo-theme-default/dist/all.scss';

2. The code required to replace the previously customized variables with the migrated variables looks like this:

   // New code (used with theme version v8.0.0):
   
   // Using the 'k-generate-color-variations' function to migrate the customized colors:
   @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),
     ),
     k-generate-color-variations('primary', #9c27b0, 'default'),
     k-generate-color-variations('secondary', #e51a5f, 'default'),
     k-generate-color-variations('info', #0058e9, 'default'),
     k-generate-color-variations('success', #37b400, 'default'),
     k-generate-color-variations('base', #eaeaea, 'default')
   );
   
   // Import a theme (for example, the default theme).
   @import '@progress/kendo-theme-default/dist/all.scss';

Replacing the Sass Variables

Once you assign the custom color values to the new variables, remove the previously used variables from your codebase. The recommended way of doing this is by using the k-color() function. For more details, refer to the Predefined Color Variables section of each theme.

The next example shows how to replace the Sass variables:

1. The starting point is a code sample with the previously used variables:

   // Old code (used with theme versions before v8.0.0):
   @import '@progress/kendo-theme-default/dist/all.scss';
   
   .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;
   }

2. The code required to replace the previously used variables with the migrated variables looks like this:

   // New code (used with theme version v8.0.0):
   @import '@progress/kendo-theme-default/dist/all.scss';
   
   // Using the 'k-color()' and replacing the previously used variables:
   .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);
   }

Backward Compatibility

By default, the new Color System in the Telerik and Kendo UI themes is enabled—this means that the new Color System is used by default.

To disable the new Color System, set the $kendo-enable-color-system variable to false prior to importing the theme—this lets you postpone the migration.

$kendo-enable-color-system: false;

// Import a theme (for example, the default theme).
@import '@progress/kendo-theme-default/dist/all.scss';

Disabling the new Color System lets you use the previous color variables. However, this is not recommended as the new Color System provides a more predictable, consistent, and easier way to customize the colors in the theme. The $kendo-enable-color-system variable will be removed in one of the next major versions of the Telerik and Kendo UI themes.