Code conventions

JavaScript

We prefer to use JavaScript sparingly. We’re using Stimulus JS for the components that require more interactive behavior. We also use jQuery throughout the project.

CSS

The project uses the [Sass] preprocessor. We use Sass variables for almost everything, except for colors, which use CSS custom properties. We use CSS custom properties (or CSS variables) for color in order to easily swap between different color themes.

CUBE CSS method

The CUBE method describes how we prefer to organize our CSS. Here are the basics of the CUBE acronym:

Composition: high-level classes for organizing layout such as stack and vertical-spacing.

Utility: Single-rule classes like u-font-weight-bold, u-display-flex, and m-top-lg (margin).

Block: Specialized classes for specific components such as firm-admin-layout or dropdown. For nested block classes we use a BEM naming scheme which has double underscores to seperate blocks and their children, e.g. dropdown__modal.

Exceptions: Class modifiers to denote a slight change in presentation or behavior. Exceptions are denoted by a double-hyphen following the base class name, e.g. dropdown__modal--align-right.

Read the introduction to CUBE CSS.

A quick and dirty reference for naming component classes:

/* This is the basic structure of a class name */
.block__element--modifier {

/* An example */
.site-header__logo--large {

A few guidelines:

1. Use single hyphens for multi-word names:

    .block-name__element-name--modifier-name {…}
   

2. Don’t nest multiple elements:

    .block__element__element {…} // wrong
   

3. The base element should always come first when ordering multiple classes. Typically this means it is at the top of the file.

    .block {…}
   
    .block--modifier {…}
   
    .block__element {…}
   
    .block__element--modifier {…}
   

4. Modifiers always go immediately after the class they are modifying.

    .block__element {…}
   
    .block__element--modifier {…}
   
    .block__other-element {…}