CSS Guidelines

BEM Naming Convention

Use our version of the BEM style syntax, and split components of UI up into discrete reusable modules (one Sass file per module).

.module {}
.module__element {}
.module--modifier {}
.module.is-state {}
.u-utility-name {}
.t-theme-name {}
.js-button {}

If you need to provide a hook for selenium tests, then use ids.

Syntax

• Class names are hyphen separated (not camelCase)
• Do not use IDs for css selectors
• Opening curly bracket on same line as the rule set
• Indentation is 4 spaces (no tabs)
• Each property on its own line
• Insert a space after the colon
• All rules should end in a semi-colon
• Colour declarations should be lowercase hex values (unless using rgba) using the short form where possible
• If you have multiple selectors separated by commas, then each selector should appear on its own line (see example)
• Leave a blank line between each style block

Note, if your project is using stylelint then use stylelint-config-bright to enforce the above rules.

.my-style {
    display: block;
    width: 200px;
    float: left;
    border: 1px solid #333;
    background: #eee;
    font-size: 12px;
}

.my-style > h3,
.my-style > p {
    margin-bottom: 0;
}

Comments

When using Sass, always use the Sass style comments as they will be automatically stripped out of the generated CSS for you.

Comments should be sentence case, appear on their own line (not following some code), and do not need a colon.

// ------------------------------------------------------------------
//  Top level comment
//  Used to introduce the module, and give any usage instructions.
// ------------------------------------------------------------------


//  Second level comment, for organising the module
//  into sections. Two empty lines above, one below.
// ------------------------------------------------------------------

// Simple comment to annotate the code

The following Gists provide sublime text snippets for top-level (tab trigger = cb) and second level (tab trigger = cb2) Sass comments.

Nesting

When using Sass, avoid excessive nesting as it increases the specificity of your css for no good reason. Consider adding more BEM-style classes to avoid unecessary nesting.

// BAD
.teaser {
    .teaser__header {
        ...
    }

    .teaser__button {
        ...
        .teaser__icon {
            ...
        }
    }
}

// GOOD
.teaser {
    ...
}

.teaser__header {
    ...
}

.teaser__button {
    ...
}

.teaser__icon {
    ...
}