This guide should be thought of as a default rather than an absolute. If there’s a good reason for doing something differently that’s fine. The important thing is to make sure that each component is internally consistent and the overall level of code quality is high. The only requirement for making an exception is that you’re able to provide a good reason if someone asks you why.

Javascript

• Reference DOM elements using data attributes.
• Make sure to add error checks for any missing DOM elements.
• Make the files as small as possible.
• SCSS files which style javascript behaviours should be kept in the same directory

SASS

General

• If an element in a component needs styling it must have its own style, rather than using CSS inheritance. This allow us to target elements and reuse styles more efficiently.
• Don’t hard code colours - use the theme colours instead.
• Favour rem over pixels.
• Avoid adding position properties to component styles. Components should not position themselves.
• Avoid adding external spacing properties to component styles. Components should not mandate layout themselves.
• Nest as much as necessary, and as little as possible.

BEM

Use BEM where it makes sense, and default to nesting using ampersands e.g. this

.block {

    &__element {

    }

    &--modifier {

    }
}

If it makes sense to write selectors out longhand, e.g. because it works better with the required media queries, then that’s fine. Making the code readable and easy to maintain is more important than absolute consistency.

General

Avoid repeated behaviours and styles Even if you have to refactor other components to avoid the repetition.