Working with stylesheets

Introduction

We use Sass (or rather SCSS, a sassy superset of CSS) to write our CSS rules. All SCSS stylesheets are compiled to plain CSS in the maven build cycle using gulp through the frontend-maven-plugin.

We also use Bootstrap 4 to provide us with some basic components, which we customize for our themes.

Compiling the stylesheets

In maven lifecycle

The stylesheets are automatically compiled when you run a maven build of the view. You can compile or package only the view by running ./mvnw compile -am -pl view or ./mvnw package -am -pl view respectively in the root of the repository. It is also built automatically when you compile the whole project with ./mvnw compile.

On the fly

It's tedious and slow to always have to run separate maven builds. While developing, you will likely want to watch the files and have them compile automatically. You can do so using gulp (make sure you've installed the gulp-cli in your machine) in the view directory:

gulp watch

As long as you don't close the terminal or cancel it, your stylesheets will be compile automatically.

Structure

Our style rules can be split into 3 logical parts:

1. Rules taken from Bootstrap, customized via Bootstrap's variables
2. Extensions of Bootstrap components with our own style rules
3. Fully custom components and rules

All our stylesheets can be found in the view/src/main/resources/static/sass folder and are written in SCSS.

1. Basic Bootstrap

We import all the components that we need in the bootstrap/_bootstrap-custom.scss file. This file imports our bootstrap/_custom-variables.scssfile, which overrides some of Bootstrap's provided variables to customize the look and feel to match out themes.

2. Extended Bootstrap

When we extend a bootstrap component, we do so in a file named after the component in the bootstrap/custom folder. Extending may include adding a new variant (e.g. the cb-bg-noise utility class that adds a noisy background image), customize the structure of existing components (e.g. the navbar), or adding a new element inside a component (e.g. the cb-btn__image, which allows using image icons inside buttons).

Any new CSS class we create for this purpose bears the prefix cb-(custom bootstrap), but aside from that follows bootstrap's naming convention.

3. Custom components and rules

The partials are split into several folders:

base       # contains some page-wide defaults, no class selectors!
layout     # contains basic layout rules, `l-` class prefix
components # contains custom components, `c-` class prefix
pages      # contains page-specific rules, `p-` class prefix

If you create a new partial, make sure you import it in the partial with the same names as the folder, as it won't be included in the final stylesheet otherwise.

Naming conventions

For our custom components, we follow a naming convention inspired by BEM (Block, Element, Modifier). Most our rules are in the form of components located in the partials/components folder. The classes within components follow the naming convention c-ComponentName__elementName--modifier.

Layout and page rules also follow a similar naming pattern. Page-specific classes are of the format p-PageName__elementName--variant and layouts are of the format l-LayoutComponent__element--variant.

Variables

All theming is done via variables that are defined in the variables folder. The base variables are in the _t-base.scss file. All variables have the !default flag, allowing them to be overridden from other theme files.