CSS Conventions

CSS Pre-processor: Sass

The css extension language Sass will be used for all Platform css. Css files will be created using the .scss extension and compiled in to one master .css file.

Nesting

Use a comment when closing a nested group:

Do not nest more than 3 levels deep

Declaration Order

Cluster related properties as follows:

Start with element structure styles (margin, padding, size)
Continue with color and font styles
End with exterior styles (borders)

Variable Naming

When naming variables use relative terms, for example primary-color instead of primary-blue. Some options include base, primary, secondary, tertiary, highlight, main, sub, etc.

When creating a variable for a color in the site overrides, add a comment with what the color is.

Mixins

Use mixins for media queries, clearfix, gradients, and other special styles that come up multiple times

Media Queries

All media queries should be mobile first - write out the styles for mobile first, and then add media queries for each increasing screen size change. The media queries will be used inline with the element using Sass mixins.

CSS Methodology

Css will be written using a combination of the BEM (Block Element Modifier) and SMACSS (Scalable and Modular Architecture for CSS) methodologies.

BEM

BEM syntax will be used for class names.

Avoid IDs for styling

Do not use IDs to style elements because of the higher specificity.

Naming conventions

Use .block__element--modifier syntax for naming classes.

Blocks

A block is a top-level abstraction of a new component, also known as the parent. Use a single hyphen ('-') for compound words.

Try to keep all instances of block styles in one stylesheet.

Elements

Elements are child items that are placed inside blocks. They are written with two underscores ('__') between the block and the element. Grandchildren elements are allowed but great-grandchildren should not be used.

Modifiers

Modifiers are used to manipulate blocks for style variations. A modifier is attached to the end of a block or element with two hyphens ('--'). Do not chain modifiers. Do not create elements as children of modified blocks.

When using modifiers do not repeat them in the css, repeat them in the HTML.

SMACSS

SMACSS syntax is used for state classes (style changes that happen when a user interacts with the site).

Use the .is-* state class when there is a change on an element itself

Use the .has-* state class when there is a change to the child of an element.

View all examples here: https://github.com/DivcomWebTeam/platform_base_theme#9-css-conventions