CSS Style Guide

Overview

Usually this will be determined by the project’s framework or existing setup but in all cases we use Sass method. Unless there’s a substantial reason otherwise then always use Sass for preprocessing your CSS. At the time of writing the CSS variables specification is coming on as a potential replacement for this, however, this is not confirmed.

BEM naming method

When writing Sass use the BEM methodology to its full capacity ensuring that properties aren’t deeply nested and others can understand where to find different code blocks. Try to keep components, layout and plugins separated and as modular as possible over separated files and folders.

The syntax variant we use for Sass is SCSS.

Example of BEM layout with HTML and Sass markup in SCSS syntax:

<ul class="list">
    <li class="list__item">Item 1</li>
    <li class="list__item">Item 2</li>
    <li class="list__item list__item--end">Item 3</li>
</ul>

.list {
    padding:0;
    margin:0;
}

.list__item {
    list-style:none;
}

Use variables in a separate file that is similarly using the BEM naming method. Make the name of the variable clear to others who might be editing later and avoid using specific colours, numeric sizes or properties as part of the name, e.g. "$button__red".

$color__primary--light: #DD0000 !default;
$color__primary: #C10000 !default;
$color__primary--dark: #990000 !default;

$base__font-size: 15 !default;
$base__line: 20 !default;

For element states use the double hyphen combine with ampersand nested within the related group.

.button {
    &--active {
        background-color:blue;
        color:#FFF;
    }
}

When grouping together different properties and nested states or variations aim not to have more than 3 layers of nesting.

Use Sass parent selectors to avoid separation of related properties where an affected element relies on a class from, for example, the body element.

<body class="show--mobile-navigation">
    <head>
    </head>

    <nav class="mobile-navigation">
        ...
    </nav>
<body>

.mobile-navigation {
    display:none;

    .show--mobile-navigation & {
        display:block;
    }
}

Inline styling

There are only some occasions that it may be acceptable to use this method for applying CSS styles. This includes email builds, for CSS-in-JS methods such as React-based applications and for CMS output of custom fields such as when the client/user wishes to customise colours of content and layouts.