Stylesheet coding standards

Code style standards for CSS and Sass

Our stylesheet coding standards are based on BEM methodology.

All class names in the codebase are built of three parts:

  • Block: The sole root of the component.
  • Element: A component part of the Block.
  • Modifier: A variant or extension of the Block or Element.

The point of BEM is to give a lot more transparency and clarity to your markup. This naming structure informs developers how classes relate to each other, which is particularly useful in complex or deep pieces of DOM.

There are a number of common problems when working with CSS at scale, but the major two that this document aims to solve are clarity and confidence:

Clarity: How much information can we glean from the smallest possible source? Is our code self-documenting? Can we make safe assumptions from a single context? How much do we have to rely on external or supplementary information in order to learn about a system?

Confidence: Do we have enough knowledge about a system to be able to safely interface with it? Do we know enough about our code to be able to confidently make changes? Do we have a way of knowing the potential side effects of making a change? Do we have a way of knowing what we might be able to remove?

Naming convention





Always encapsulate a component in a component name and all elements of the component is prefixed with the component name. For example:

<div class="user">
    <img class="user__image" src="/jeff.jpg" />
    <p class="user__name">Jeff</p>

New code should be written using the full class names, to enable findability and to lower the cognitive load of navigating a medium to large partial. For example:

.user {

.user__image {

.user__image--small {

Targeting elements

As a developer, you should only target elements in the core part of your CSS styles. Such as the reset and typography. This results in all elements that have component styling need a class attached.

Utility class





Utility classes are styling patterns that are used across the entire site and can be applied to modify components. We should strive to keep this to a minimum as they lead to a lot of single style overrides.

Semantic naming


Naming components can be difficult as the name should be based on the reasoning for the styling and not on the style being applied. Styling can change which makes the name incorrect and confusing. Component names can contain more than one word which are separated by a single hyphen:



When naming an element, use a word or words that best describe the content of the element. Again, these can contain more than one word separated by a single hyphen:

<ul class="list">
    <li class="list__item"></li>


Modifiers should describe the reason to have overriding styling. Again, these can contain more than one word separated by a single hyphen:

Do not:

<div class="row--grey"></div>


<div class="row--billboard"></div>

Nesting elements

You may find you start to nest elements inside a component. This should be done with semantically named elements. You should only have one element name for each DOM element. For example:

Do not:

<li class="nav__list__item"></li>


<li class="nav__list-item"></li>

If you find you are having trouble naming an element due to over nesting, consider splitting that component into smaller components that when combined become result in the desired organism.

Example of a component with nested elements:

<nav class="nav">

    <ul class="nav__list">

        <li class="nav__list-item">
            <a href="#" class="nav__link">Link</a>

        <li class="nav__list-item">
            <a href="#" class="nav__link--promo">Promo</a>



State classes

is-, has-: Signify that the piece of UI in question is currently styled a certain way because of a state or condition. It tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked.


.[is|has]-state {}




This allows interactive scripts to simple toggle these classes with confidence only state styles will be effect. Leaving component styles unaffected.

JavaScript namespacing

A piece of the DOM has some behaviour acting upon it, and that JavaScript binds onto it to provide that behaviour. If you’re not a developer working with JavaScript, leave these well alone.





The idea is that – in order to properly separate our concerns, we should never have styling and behaviour bound to the same classes.

Code Formatting

To ensure consistency across our codebase, we use Prettier for formatting Sass.

Stylesheet Linting

To ensure conformity and correctness in Sass files across our codebase, we use Stylelint to lint our Sass files. We use the stylelint-config-recommended shared configuration as it plays nicely with Prettier.