CSS style guide

A guide on how to write and structure CSS and SCSS code for the Front-end of all of the Claromentis projects

Syntax and Formatting

All CSS/SCSS should follow the structure outlined here

CSS

Copy
.card .card-header {
    color: red;
    background: rgba(0, 0, 0, 0.3);
    margin: 0;
    border: 1px solid var(--purple);
    opacity: 0.4;
    padding: 1.5rem;
}

Things to note when writing CSS:

• Strings in classes are delimited with a hyphen (-) aka “kebab case”.
• Leave a space after : in property declarations.
• Leave a space before { in rule declarations.
• Make sure all CSS declarations are on their own line.
• Closing braces } should be on a new line.
• Make sure no unneeded whitespace is left before the closing bracket.
• Use rem units where possible when specifying sizing and spacing.
• Avoid specifying units for zero values, e.g. margin: 0; instead of margin: 0rem;.
• Write rgb and rgba parameters with the above structure (leave a space after each parameter).
• Always use leading zeros for decimal values e.g. opacity: 0.4; instead of opacity: .4;.
• Add spaces before and after child selector e.g. div > span instead of div>span.
• Add a semicolon to the end of a property/value declaration.
• Use 4 x spaces for tabbing/indentation.
• Accompany all new styles with a comment describing what it does.
• Avoid increasing specificity by repeating selectors as it results in unmanageable code

SCSS

Copy
// Comments should be written like this
.card .card-header {
    color: $red-400;
    background: rgba(black, 0.3);
    margin: 0;
    border: 1px solid var(--purple);
    opacity: 0.4;
    @include transition(background 0.5s ease);

    .card-title {
        color: $gray-600;
        font-weight: bold;
    }
}

Things to note in addition to standard CSS:

• Leave an escaped line between parent SCSS declarations and nested selectors.
• Make sure all SCSS comments are written in the // style.
• rgba declarations can be written in the above style using a colour or variable (make sure a space is left after the colour parameter).
• Grouping @include functions at the end makes it easier to read the entire selector.
• List all standard property declarations, ordering by importance. Anything that isn't an @include or a nested selector.

Things to avoid when writing your CSS/SCSS code

• Avoid using HTML tags in CSS selectors
  • E.g. Prefer .modal {} over div.modal {}
  • Always prefer using a class over HTML tags (with some exceptions like CSS resets and global browser styling overrides).
• Don't use IDs in selectors
  • #header is overly specific compared to, for example .header and is much harder to override and is not reusable in other places.
  • Read more about the headaches associated with IDs in CSS here.
• Don’t nest SCSS more than 3 levels deep
  • Nesting selectors increases specificity, meaning that overriding any SCSS set therein needs to be targeted with an even more specific selector. This quickly becomes a significant maintenance issue.

Editor Config

For product development, there is a file at the root of the Claromentis Core project named .editorconfig. This file can be used by various editors / IDEs (if enabled) to adhere to the code style defined within it. This helps maintain consistent coding styles across the project.

Conventions & Functions

JavaScript hooks

Use a JavaScript-specific classes to bind javascript functionality to, this should be prefixed with .js- so it can be identified easily:

HTML

Copy
<div class="news-article js-new-article">
</div>

JS

Copy
// Jquery
$('.js-news-article');

or

// VanillaJS
document.getElementsByClassName('js-news-article')[0];

SCSS file structure

• Use the .scss syntax, never the original .sass syntax.
• Include @import declarations at the top of the file.
• Add variables and @mixin at the top of the file (below @import declarations) before adding any CSS rules.

Mixins

Mixin are powerful but can contribute to unnecessary code duplication in compiled stylesheets. Avoid mixins containing deprecated properties and vendor prefixes. Below is an example of a @mixin:

Copy
@mixin center {
    margin: {
        left: auto;
        right: auto;
    }
}

Include all mixins at the top of the page before utilising them
<-- / -->

.center {
    @include center;
}

Operators

Use math operators where possible. SCSS has a handful of standard math operators like +, -, *, /, and %. Below is an example of how math operators can be used:

Copy
.col-3 {
    width: 100%/4;
}

Controlling colour with SCSS

When using functions to calculate colour make sure there is enough contrast between text and backgrounds. Please refer to Accessibility section.

Media Queries

When possible media queries should be within the CSS selector as per SMACSS using Boostrap's breakpoint mixins . Below is an example of the Bootstrap breakpoint mixin in use:

Copy
.selector {
    float: left;

    @include media-breakpoint-up(md) {
        float: none;
    }
}

• If you're unable to place media queries with the CSS selector they should be placed as close to their relevant rule sets. Don't bundle them at the end of the document, for doing so only makes it easier miss them in the future.

Element Queries

To achieve more granular control over component display in Pages grid, gridstack.js data attributes can be targeted in CSS. This together with media queries offers good control over how components display at various breakpoints. Below is an example of the Gridstack element queries in use:

Copy
//Allows the control of the styling of the Anniversary component when it is at 1 pages block wide
.anniversary-grid-item[data-gs-width="1"] .content-block {
    .anniversary profile-img {
        width: 35px;
        height: 35px;
    }
}