SCSS coding standards

Why SCSS coding standards?

Like any coding standard, SCSS coding standards is also aiming for improving collaboration, code quality and enabling supporting and maintenance infrastructure. The list can be very long if we really dig into small details, below content is only for the key points we need to be most aware of.

Formatting

Put spaces after : in property declarations.
Put spaces before { in rule declarations.
Use one line per property declaration.
Use two space indent or set Code Editor tab to two space. How to set VS Code text indentation
Don’t nest more than four levels.
Put similar properties together.

Code sample
.example-class { display: flex; flex-direction: column; align-items: flex-start; position: relative; margin: 0; padding: 0; .child { flex: 1 1 auto; span { text-transform: uppercase; } } }

Mixin / Extend

We use @mixin only for reusable functionality and block of properties with multiple elements. If a repeatable properties needs to be reused for multiple elements, using @extend is the way to go to keep code clean and consistent.

We have some default mixins already setup in our theme to cover most case scenarios, before creating a new mixin, double check the theme, it might already exists.

When creating a new mixin, make sure it is generic enough so that it can be reused across the project.

When using @extend, only extend placeholder, do not extend class or id. To know more details of why: https://daveredfern.com/use-sass-placeholders-and-extend-wisely-a-cautionary-tale/

Code sample

%title-attribute {
  font-weight: $bold;
  font-family: $title-font-family;
  line-height: 1.3;
  color: color(black);
}

h1 {
  @extend %title-attribute;
  font-size: rem(40);
}

h2 {
  @extend %title-attribute;
  font-size: rem(30);
}


@mixin fake-full-width($fake-bg: #666) {
  position: relative;
  z-index: 1;
  
  &::before {
    content: "";
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 50%;
    margin-left: -50vw;
    width: 110vw;
    background: $fake-bg;
    z-index: -1;
    background-size: cover;
  }
}

.card {
  @include fake-full-width(color(black));
}

Unit

em - margins and padding for text blocks where space should scale with the font size

rem - Most commonly used. Component dimension ( width / height ), Spacing ( margin / padding / gap ), font size, etc

px - Only use for small values ( <5px ) such as border thickness or border-radius

vw / vh - Only use those units creating styles that are responsive to the size of the viewport. Such as responsive images, containers, etc. Can be used for Fonts ( use clamp() to make sure font size won’t go too small or too big for A11y ).

% - Only use the unit creating styles that are responsive to the size of the container, responsive layouts, responsive images, font line-height, etc. Avoid using it for font-size.

vmin / vmax - relative to 1% of the smaller/larger dimension of the viewport. If design is provided to scale base on the orientation of the device, those units can be considered.

ch / ex - ch ( Relative to the width of the "0" ), ex ( Relative to the height of the character "x" ) We don’t normally use those units.

cm / mm / in / pt / pc - The absolute length units are mostly being used for prints. Please don’t use them.

Media Queries

We have a build in node package for media queries - Breakpoint-SASS, and variables for different break points, please use the variables instead of custom values, and do not use the default css media queries selector.

For breakpoint variables, checkout file settings/breakpoint.scss

Code sample

:hover,
:focus,
:active,
:visited

We put single : in front of :hover, :focus and :active pseudo classes.
The :hover is used to apply styles to an element when the user hovers over it with their cursor.
The :focus is used to apply styles to an element when it is currently in focus, such as when the user clicks on it or tabs to it using the keyboard.
The :active is used to apply styles to an element when it is being clicked or touched by the user.
The :visited is used to apply styles to links that have been visited by the user. It needs to match the default state of the element to eliminate privacy concerns.

It is critical to not miss any of the states for the interactive elements, most commonly links, buttons, menus, etc. For the end user to have a better navigate experience on variation of devices they are using. And never remove the :focus and :active states in any situations.

::before, ::after
We put double :: in front of ::before and ::after pseudo elements.
Those elements are commonly used to add decorative elements, such as icons or texts, to an element without modifying its HTML.

Avoid using them to add important content to any components. If the CSS file fails to load, the content will be lost on the web page.

Comment

Refer to https://kalamuna.atlassian.net/wiki/spaces/KALA/pages/2790817793

Naming

We are using BEM as our naming convention. Please refer to https://getbem.com/naming/

Keep your code DRY(don’t repeat yourself)

Use CSS/SCSS variables, if no variable is existing and it’s for multiple usages, create one.
Use placeholder if a group of properties is being used in multiple places.
Use mixins if a group of properties is being used in multiple places with different values.
Use functions Simplythemes provided ( color(), space(), rem(), etc.)

Things to avoid

Avoid using !important , instead, use more specific selector to overwrite when possible.
Avoid extending selectors ( class, ID, element ), always extend placeholders.
Avoid using px, use rem() function. /* Small values ( < 5px ) such as border thickness or border-radius can be exception based on situation */
Avoid custom breakpoints.
Avoid using em for breakpoints.
Avoid nesting too deep ( more than four levels ).