SCSS Style Guide

This document outlines best practices on writing semantic, scalable, and modular CSS. Note that these guidelines assume the use of SASS, a CSS pre-processor, and more specifically, the SCSS syntax. The basis for this guide is to outline distinct rules to format and write SCSS, though the principles outlined here can be applied to CSS or SASS syntax as well.

This guide borrows concepts from Code Guide by @mdo, Idiomatic CSS, and BEM.

Code Formatting
Specificity & Naming
Units
Ordering
Linting

Code Formatting

Declaractions

Use soft tabs with a two space indent
A selector should have a single space between the name and the {
A property should have a single space between the : and the value
There should be only one property per line
Unrelated or non-sequenced selectors should have a single new line between them
Colors should be specified in hex or rgba values
Hex values should be in lowercase and use shorthand if possible (e.g., #fff)
rgba values should utilize SASS conversion to maintain the hex value (e.g., rgba(#fff, 0.5))
Comma-separated values should have a single space after the , if they appear on a single line
Multiple comma-separated property values should appear indented on multiple lines with one declaration per line
Decimal values should start with a leading number before the . (e.g., 0.5)
Psuedo selectors and elements should be denoted using a single : (e.g., :hover, :before)
Vendor prefixes should be taken care of by an autoprefixer
Use single quotes (e.g, 'foo')
Do not specify units for zero-values (e.g, margin: 0)
Single property declarations should appear on a single line
Multi property declarations should appear on multiple lines with one rule per line
Mixins without properties should omit the () (e.g., @include my-mixin)
Avoid the use of SASS color functions (e.g., lighten(#000))
Avoid the use of !important

Comments

Use the SCSS comment syntax (//) for all comments
Use comment headings appropriately

Example

//
// This is a comment heading
//

//
// This is a comment block heading
//
// Iaculis velit a laoreet consectetur mollis dignissim diam fringilla,
// commodo vulputate turpis dis praesent lacus lorem, justo accumsan
// platea scelerisque pharetra viverra id.

// This is a good example
.foo,
.bar {
  position: absolute;
  display: block;
  font-family: 'Times New Roman', serif; // This is another good example
  font-size: 20px;
  color: #000;
  text-shadow:
    0 1px 2px #ddd,
    0 2px 2px #aaa;
  content: 'Hello world';
  background: rgba(#fff, 0.15);
  box-shadow: 0 0 10px 0 #000;
}

.foobar {
  color: #fff;

  &:hover { text-decoration: underline; }

  &:active { font-weight: bold; }
}

.biz { font-size: 16px; }
.baz { font-size: 24px; }

Units

Use px for things that should scale in a fixed manner
Use rem for things that should scale with the root font-size
Use em for things that should scale with the element font-size
Use % for things that should scale with the parent element
Use vw and vh for things that should scale with the viewport
line-height should be a unitless multiplier of font-size

Specificity & Naming

Rule Specificity

Rules and properties should only be as specific as they need to be. Ideally, your selectors should maintain a flat structure.

// Bad 🙁
.grandparent .parent .my-selector {
  ...
}

// Good 😀
.my-selector {
  ...
}

Selectors

Always use class selectors
Do not use ID selectors
Do not use type selectors
Do not mix class selectors with ID or type selectors
Use attribute selectors wisely

Adhering to these guidelines increases the amount of style resuability and reduces the amount of overriding that needs to be done in the CSS codebase.

// Bad 🙁
div {
  ...
}

div.my-selector {
  ...
}

#my-selector {
  ...
}

// Good 😀
.my-selector {
  ...
}

Naming Conventions

Rules should be named semantically so that someone looking at just the markup should be able to determine what that rule is going to do.

Use BEM style for components
Use kebab-case for multiple words (e.g., .my-block)
Use two underscores (__) to separate blocks from elements (e.g., .my-block__my-element)
Use two dashes (--) to separate modifiers from blocks or elements (e.g., .my-block--my-modifier or .my-block__my-element--my-modifier)

// Component Classes
.media {
  ...

  &__object {
    ...

    &--reversed { ... }
  }

  &__body {
    ...
  }
}

// Utility Classes
.text-sm { ... }
.text-md { ... }
.text-lg { ... }

Class names are broken down first into a block (.media). Then, into elements (.media__object and .media__body). And finally into modifiers (.media__object--reversed).

Nesting

While nesting is a great feature of SASS, it can easily make things much more complex and hard to digest. Nesting should be limited to 3 levels or less.

Extending

While extending selectors (@extend) is a great feature of SASS, it can easily make the output CSS much more complex and hard to digest so it is best to avoid using them. More often than not, it would make more sense to pull something out into a mixin rather than use an extend.

Shorthand

Limit the use of shorthand declarations if you do not need to explicitly set additional declarations.

// Bad 🙁
.my-selector {
  margin: 10px 0 0 0;
  border-radius: 4px 0 0 0;
}

// Good 😀
.my-selector {
  margin-top: 10px;
  border-top-left-radius: 4px;
}

Media Queries

SASS allows media queries to be nested inside of a selector. This can make our code very easy to digest when working in responsive styles.

.my-selector {
  ...

  @media (min-width: 1024px) {
    ...
  }
}

Variables

SASS variables should be used wherever a property value may need to be repeated across the codebase (e.g., color values, breakpoints).

Use kebab-case (e.g., $color-white)
Use semantic naming conventions

// Bad 🙁
$alpha: #000;
$beta: #fff;

// Good 😀
$color-black: #000;
$color-white: #fff;

Ordering

Order side values by top, right, bottom, left
Declare mixins first, then regular properties
Psuedo selectors should come before other selectors

.my-block {
  @include my-mixin;

  // Positioning
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 10;

  // Box Model
  box-sizing: border-box;
  display: block;
  width: 100px;
  height: 100px;
  padding-top: 10px;
  padding-bottom: 10px;
  margin: 10px;
  overflow: hidden;

  // Typography
  font-family: 'Times New Roman', serif;
  font-size: 1rem;
  font-style: italic;
  font-weight: bold;
  line-height: 1.5;
  color: #000;
  text-align: center;
  text-decoration: underline;
  text-shadow: 0 1px 0 #fff;
  text-transform: uppercase;

  // Accessibility & Interaction
  cursor: pointer;

  // Background & Borders
  background: #aaa;
  border: 10px solid #000;
  box-shadow: 0 0 10px #000;

  // Transitions & Animations
  transition: all 100ms ease;

  &:before { ... }

  &:hover { ... }

  &--my-modifier { ... }

  &__my-element { ... }
}

Linting

It is best to leverage a linter like stylelint to make it easy to adhere to the following guidelines. You can install this repository through your package manager and point to it in your own stylelint config file. Alternatively, you can copy the stylelint config file (.stylelintrc) included in this repository into your project.

Installation

Yarn

yarn add stylelint scss-style-guide --dev

npm

npm install stylelint scss-style-guide --save-dev

`.stylelintrc`

{
  "extends": [
    "scss-style-guide"
  ]
}

alexchantastic/scss-style-guide