Theming Propeller

Introduction

Sass stands for Syntactically Awesome Stylesheets Sass. It's a way to write the CSS using variables, nested rules, and functions which encourages reusability and makes development and maintenance task easier.

For instance, to change the color of an item in all the pages, you have to search it everywhere and make the necessary changes. But now, theming is accomplished by Sass variables and Sass maps. So, changing the value of one variable will apply changes wherever needed.

Importing

In your custom.scss, you’ll have to import Propeller’s source Sass files. You have two options available to include Propeller Pro Sass Files: either import all or pick the standalone parts as per your requirement. For beginners, we suggest using the full import stack from our propeller.scss file.

With that setup in place, you can begin to modify any of the Sass variables and maps in your custom.scss.

Variable Defaults

A lot of customization in your theme can be done using the Propeller Pro's pre-defined variables. You can find all the pre-defined variables in the _variables.scss file.

Every Propeller Pro Sass variable includes a !default flag which depicts default values of the variables. Just copy and paste the variables to be modified in your file and modify their values.

While overriding the variables in same file, it doesn't matter whether they are overridden before or after the definition of default variables. However, if you are overriding the Sass variables in your files, override them before you import the Propeller's Sass files.

For example, to change background-color and color of the body tag, just call the variable above the import in your file as shown below:

You can modify all the variables including the global options by repeating the same process.

Maps and Loops

Propeller Pro has defined a few Sass Maps, the key-value pairs to make it easier and faster to generate families of related CSS. We have used Sass Maps for our colors.

Just like Sass variables, Sass Maps also have default values which can be overridden by defining them in your custom.scss file.

Modify Map

To modify an existing color in our $theme-colors map, add the following to your custom Sass file:

Add Map

To add a new color to $theme-colors, add the new key and value:

Required Keys

Some of the keys are important to be present in the Sass Maps as we have used them in different places. So modifying their default values might not create any problem but removing them can lead to Sass compilation issues. In this case, you might need to modify the Sass code where these values are used.

Functions

Propeller Pro uses the following function for getting values from the theme-colors map:

This function allows you to pick one color from a Sass map which is similar to defining a custom class for a particular color like .red.

Propeller Pro also has a function to get a particular level of a color from the $theme-colors map same as in Bootstrap 4 4. Negative level values will lighten the color, while higher levels will darken it.

For example, to get a particular shade of your primary color, you just need to call the function in your file and pass the two parameters: primary and the numeric level of that shade.

Color Contrast

We have also included the color contrast function .color-yiq same as in Bootstrap 4 4. This function automatically returns a light (#fff) or dark (#111) contrast color based on the specified base color. This function is mainly useful for mixins or loops where you’re generating multiple classes.

For example, to generate color swatches from our $theme-colors map:

It can also be used for one-off contrast needs:

You can also specify a base color with our color map functions:

Color

Various Propeller Pro components use a series of colors defined in the Sass map. This map can be looped over in Sass to quickly generate a series of rulesets.

Theme colors

The color scheme of Propeller Pro is defined in the $theme-colors Sass map or by using Sass variables such as primary, success, etc in our scss/_variables.scss file. You can modify these variables to define the color pallette of your project.

Create or overwrite the variables within the Sass map to update the look and feel of your theme components.

Text colors

Propeller Pro also provides a predefined map - $pmd-theme-colors which can be used to set the text color of the content in any application in both dark and light background. primary parameter is used to update the color of headings, titles or any primary content while the secondary parameter is used for body text and paragraphs. Also parameters disabled, hint, hover, icons and dividers are defined to update the color scheme of disabled text, hint text, hover state, icons and dividers.

To modify an existing color in the $pmd-theme-colors map, add the following to your custom Sass file:

You can use the map in the following way:

Here we have applied primary color to the .product-list-item when it is placed in a dark background.

Box Shadow

As per the Google's Material Design standards, every component has a depth which determines how far or raised the element is from the page. So, we have included a new map $pmd-box-shadow to set the z-depth of the components. The dark parameter is used to apply the box-shadow to the components and follows material design standards. However if you wish to provide a lighter shadow or a custom shadow you can do it using the light parameter.

Following is the map defined for the same:

You can use the map in the following way:

Here we have applied z-depth-1 level of the material shadow to the .product-item.

Components

Many Propeller Pro components are built with @each loops that iterate over a Sass map which helps in generating the variants very easily. As you modify these Sass maps and recompile them, all the changes will be reflected in these loops.

Modifiers

Many of Propeller’s components are built with a base-modifier class approach which means most of the stying in contained in the main component class like .btn and the style variations are contained in their modifier classes like .btn-success. These modifier classes are built from the $theme-colors map to make customizing the number and name of our modifier classes.

Here is an example of how we loop over the $theme-colors map to generate modifiers to the .btn component.