Creating a custom theme

Getting started


SASS style guide

  • Indent with 4 spaces.
  • Use BEM naming syntax. See and
  • Document everything with PythonKSS.
  • Use md, lg, xl, … (as part of modifier name) for breakpoints.
  • Use small, large, xlarge, … (as part of modifier name) for sizes.
  • Never use @extend to extend a component. Components should be as isolated as possible. They may require another component to be useful, but they should not extend another component.

PythonKSS documentation style guide

Never use numbers for section references

Use <setting|generic|base|comonent>.<BEM-block>.

E.g: component.modal.

Define dependencies last in the description

Define dependencies last in the description as follows:

/* Something

Some description.

# Depends on
- component.modal
- component.backdrop

Styleguide something.something

HTML style guide

  • Never use ID for styling.
  • Prefix IDs with id_, and write ids in all lowercase with words separated by a single _. Example: id_my_cool_element.
  • Separate css classes with two spaces. Example: <div class="class1  class2">


How it works

Icon names are virtual (icon package agnostic). The default icon names are defined in:


When adding support for an icon package (font-awesome, ionicons, …), we need to implement a set of mixins, and import those mixins before we import basetheme/3__base/all. We supply an implementation for font-awesome by default. If you just want to use fon

Extending the default font-awesome icon set

This is fairly easy. You just need to add mapping from a virtual name to a font-awesome variable for the icon in $cricon-font-awesome-free-icon-map, and add the virtual names to $cricon-extra-icon-names.

Example - adding the align right and align center icons from font-awesome:

@import 'basetheme/3__base/cricon/cricon-font-awesome';
$cricon-font-awesome-free-icon-map: map-merge($cricon-font-awesome-free-icon-map, (
    align-center: $fa-var-align-center,
    align-right: $fa-var-align-right
$cricon-extra-icon-names: align-center, align-right;
@import 'basetheme/3__base/all';

With this, cricon--align-center and cricon--align-right css classes will be available.

Adding support for another icon set

Take a look at the _cricon-font-awesome.scss file - you need to implement all of the mixins from that, and import your custom icon mixins instead of _cricon-font-awesome.scss.