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

The stylesheets are organized into scss partials in the view/src/main/resources/static/sass folder. There is one main.scss file for each theme in the themes folder, each of which will be compiled to a single main.css stylesheet (located in the view/src/main/resources/dist folder).

The partials are split into several folders:

base       # contains some page-wide defaults
components # contains custom components
pages      # contains misc styles for certain pages
themes     # contains override variable files for each theme

If you create a new partial, make sure you include it in the _components.scss partial, as it won't be included in the final stylesheet otherwise.