Core Code Concepts

To ensure the quality and consistency of the code when contributing to the kendo-themes repository, try to follow certain guidelines.

Wrap All Code in Modules

Managing dependencies in SASS
Source of the exports mixin

• Wrap all styles inside the SASS module declarations that are implemented by the exports mixin. For example, the button/layout module:

  // scss/button/_layout.scss
  @include exports("button/layout") {
      .k-button {
          border-radius: $border-radius;
      }
  }

• Provide unique names for modules inside a theme. If a module is included by several files, it will be added to the output CSS just once and from its first occurrence.

  This approach allows you to list dependencies for different components without worrying that they will be included multiple times in the output. In the following example, both the Slider and Grid components require the Button module. No matter how the components are included in the customer code, the Button styles will be imported first before any of the styles for the Slider or the Grid.

  // --- scss/button.scss ---
  @import "button/layout";
  
  // --- scss/slider.scss ---
  // dependencies
  @import "button";
  
  // Slider styles
  @import "slider/layout";
  @import "slider/theme";
  
  // --- scss/grid.scss ---
  // dependencies
  @import "button";
  @import "dropdownlist";
  
  // Grid styles
  @import "grid/layout";
  @import "grid/theme";

Split Layout from Theming Styles

Each component directory contains as a minimum the _layout.scss and _theme.scss files:

• _layout.scss—Adds styles for the layout of the component. Don't use color variables in this file.
• _theme.scss—Adds color to the layout and defines the states of the component.

// _layout.scss
@include exports("colorpicker/layout") {
    .k-colorpicker {
        border-width: $input-border-size;
        border-style: solid;
    }
}

// _theme.scss
@include exports("colorpicker/theme") {
    .k-colorpicker {
        border-color: $input-border-color;
    }
}

Check the Layout and Theme CSS Properties list for further info.

Reuse Identical Code

It is very likely that the rules for a theme are not that different from each other. You can reuse another theme by linking to it.

// --- packages/default/scss/button/_layout.scss (Default theme) ---
@include exports("button/layout") {
    .k-button {
        border-radius: $button-radius;
    }
}

// --- packages/material/scss/button/_layout.scss (Material theme) ---
// Reuse the Default theme.
@import "~@progress/kendo-theme-default/scss/button/layout";

Avoid Overrides in Derived Themes

Try using variables to share code between themes.

The following example will output two button rules for the Material theme. Instead, you can use a variable to change the radius of the button border.

// NOT GOOD
// --- packages/default/scss/button/_layout.scss (Default theme) ---
@include exports("button/layout") {
    .k-button {
        border-radius: $button-radius;
    }
}

// --- packages/material/scss/button/_layout.scss (Material theme) ---

// Reuse the Default theme.
@import "~@progress/kendo-theme-default/scss/button/layout";

// Override styles from the Default theme.
@include exports("button/layout/material") {
    .k-button {
        border-radius: $input-border-radius;
    }
}

In the following example, the new SASS variable acts as a public API of the theme, allows you to configure the theme in the derived theme, and also provides users with more control over the theme.

// GOOD
// Default theme, packages/default/scss/button/_layout.scss
$button-border-radius: $border-radius !default;

@include exports("button/layout") {
    .k-button {
        border-radius: $button-border-radius;
    }
}

// Material theme, packages/material/scss/button/_layout.scss

// Change the default value of the button-border-radius variable.
$button-border-radius: $input-border-radius !default;

// Reuse the Default theme.
@import "~@progress/kendo-theme-default/scss/button/layout";

Allow Overrides of Variables

Declare variables by using the !default specifier which will allow them to be overwritten by derived themes or customer code. For example, $kendo-component-bg: red !default;.

Exceptions from this rule are acceptable when a variable is used as an intermediate result when performing calculations and its value must not be controllable by the consuming code.

// Public variable that can be overwritten.
$icon-size: 24px !important;

// Variable for an easier computation.
$half-icon-size: $icon-size / 2;

Use Consistent Variable Naming

• When you name variables and depending on their purpose, use the following suffixes:

  • -bg—For backgrounds.
  • -border—For border colors.
  • -text—For text colors.

• When you name variables that are specific to a component, prefix them with the component name—for example, $button-border or $grid-selected-text.

• Avoid specific property names when naming variables. For example, $splitter-splitbar-width may work fine for a horizontal Splitter but makes little sense in the vertical Splitter where the same variable will set the height of the splitbar.

  Consider the following subtitutions:

  • size instead of width or height
  • offset instead of margin-left

Use Consistent Variable Naming

• When you name variables and depending on their purpose, use the following suffixes:

  • -bg—For backgrounds.
  • -border—For border colors.
  • -text—For text colors.

• When you name variables that are specific to a component, prefix them with the component name—for example, $button-border or $grid-selected-text.

• Avoid specific property names when naming variables. For example, $splitter-splitbar-width may work fine for a horizontal Splitter but makes little sense in the vertical Splitter where the same variable will set the height of the splitbar.

  Consider the following subtitutions:

  • size instead of width or height
  • offset instead of margin-left