“person writing on a white book” by rawpixel on Unsplash

Customize Bootstrap or other toolkits, ui-frameworks or ui-libraries

Theming guidelines — Part 1

Theming is a very powerful tool used in content management systems. Styling toolkits are choice of many teams designing reusable or open source systems. The goal is to extend the provided system with custom styles.

Theming guidelines

This article is part of a block of articles about theming guidelines.

Any code is generally clearer and easier to maintain when it does not use globals, css styles are global

Unnecessarily complicated theming solutions are common. Often hard to maintain, improve or update. Changes in styling are very costly to test. Libraries and system can change over time with new releases and introduce breaking changes regularly.

Teams need to have discipline when working with theming. Setting and following rules can have a great impact on the maintainability of the project.

  • write as minimal lines of CSS as possible
  • structure functionality into separated files
  • remove unused CSS code

Toolkits like Bootstrap

Toolkits provide style guide with components and default styling which is very useful for prototyping.

Some toolkits use SASS preprocessor and allow changes in the styling using variables or by adding custom CSS.

Altering styles without preprocessor

Minified Toolkit and a separate file with CSS overrides.

👍 fast for small customizations

👍 you do not have to set up the preprocessor

👎 some overrides will be very complicated, or even not possible

👎 a duplicate code will be shipped using another request

In some situations, it is the fastest way to deliver small changes. On the other hand, changing primary color can lead to hundreds of lines of code to be written. Do not use this approach since you will end up shipping large Toolkit CSS and large overrides. If you use whole bootstrap toolkit then your pages will use in average less than 2% of the styles. You will be shipping a lot of unused code.

The problem with unused styles was very common. Former versions of Bootstrap had online customize and download tool to get your version of the toolkit with custom variables and only components you needed.

Look at the tool provided for Bootstrap 3 that was using Less at the time. https://getbootstrap.com/docs/3.3/customize/

Altering styles by overriding Sass variables

Creating one minified CSS file containing toolkit code and customizations together.

👎 setting up preprocessor build pipeline with node modules

👍 SASS functions mixins, custom variable overrides

👍 toolings like autoprefixer, minification, and others

👍 full control over excluding not used Toolkit components

Sass variables are very powerful API provided by Toolkit creators. One variable can be used across the toolkit and change look of many components. Size of the output file can be lovered by disabling components that are not used by the specific application.

Theming Bootstrap

Bootstrap 4 is using Sass variables for global style preferences.

File structure

Whenever possible, avoid modifying Bootstrap’s core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you’re using a package manager like npm, you’ll have a file structure that looks like this:


In your, custom.scssyou’ll import Bootstrap’s source Sass files. You should only pick the parts you need.

Overriding default variables

Every Sass variable in Bootstrap 4 includes the!default flag allowing you to override the variable’s default value in your own Sass without modifying Bootstrap’s source code. Copy and paste variables as needed, modify their values, and remove the!default flag.

Variable overrides within the same Sass file can come before or after the default variables. However, when overriding across Sass files, your overrides must come before you import Bootstrap’s Sass files.

Read more in Bootstrap section about theming.

Best practices recapitulation

  • use npm to install the toolkit modules
  • reduce unnecessary imports from the toolkit
  • prefer overriding default SCSS variables over custom styles
  • use toolkit variables in custom styles
  • amount of custom code should be minimal

Theming guidelines