Home

Awesome

Principles of writing idiomatic Sass

While many people think of Sass as just CSS there are many unique challenges that need to be addressed if we want to be able to write the best possible code. In this document I'll go through some coding styles that will help you share code with others and avoid a common pitfalls.

In addition to many of these principles you should read Idiomatic CSS and apply standard CSS best-practices along with these. Understanding how to write great CSS is the foundation this is built upon. For this reason, there will be a bit of overlap.

Table of Contents

  1. Object-Oriented Sass
  2. Naming Conventions
  3. Selectors
  4. Properties
  5. Nesting
  6. Indentation
  7. File Structure
  8. Functions
  9. Mixins
  10. Modules
  1. Definitions

Object-Oriented Sass

Writing good Sass code starts with correctly dividing and modularizing your objects. It is arguably more important than any other aspect of writing CSS.

Well-written Sass is:

Decoupled

Objects should never manipulate other objects. eg. .message would never change the style of a nested object called .list. Instead use child selectors like .message__list and use both classes in the markup <div class="list message__list"> or use a modifier <div class="message"><div class="list list--small"></div></div>

Specific

Break functionality into smaller objects. Each object should do one thing and do it well.

Not location-based

Never, ever use location-based styling. This means a block is never styled different because it is within another block. Objects should have "modifiers" instead of location-related styles .block--large {} instead of #sidebar .block {}

Never uses IDs

Yep, never. You don't need them and they aren't re-usable by nature

Separates layout from style.

This means an object that handles background and border won't control padding and margin. Styles generally fall into a couple of categories: layout, texture, typography. Each object should generally only handle one of these. But be pragmatic about it and consider reusability at all times.

Enforce these rules by using one of the naming conventions in the next section.

Naming Conventions

It's important that you use a consistent naming convention for your selectors. For this, I recommend looking at the BEM or Montage.

BEM

.block-name {}
.block-name__child-name {}
.block-name--modifier {}

Montage

.namespace-BlockName {}
.namespace-BlockName-childName {}
.namespace-BlockName--modifier {}

The most important thing is that you pick one as a team and stick with it.

Selectors

Properties

Ordering

  1. $variable should always appear at the top.
  2. @extend should always appear before properties. It's like extending a class in Ruby.
  3. @include should appear second. This allows the properties to override the mixins.
  4. Properties should appear after this, optionally grouped by type or sorted alphabetically.
  5. Mixins with content blocks should appear next. @include someMixin { properties }
  6. Selectors that target itself. &.modifier
  7. Child selectors appear last.

The basic rule of thumb is at-rules, properties, then blocks.

Here is an example of a well-formed selector:

.selector-1,
.selector-2,
.selector-3[type="text"]  {
  $bg: blue;
  $fallback: green;

  @extend .clearfix;
  @include border-box;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
  display: block;
  font-family: helvetica, arial, sans-serif;
  color: #333;
  background: #fff;
  background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));

  @include after {
    position: absolute;
  }

  &.selector--modifier {
    background: red;
  }

  .selector__child {
    display: none;
  }
}

Nesting

Indentation

File Structure

Functions

Mixins

// Loop through each breakpoint and build
// classes for each using the breakpoint mixins
// First breakpoint is no media query — mobile-first.
// 
// @param {List} $breakpoints List of column breakpoints
// @param {Boolean} $spacing Include spacing classes? 
// @param {Boolean} $visibility Include visibilty classes? 
// @param {Boolean} $layout Include layout classes? 
// @api private
@mixin -rg-Breakpoints($breakpoints, $spacing: true, $visibility: true, $layout: true) {
  @each $columns in $breakpoints {
    @if index($breakpoints, $columns) == 1 {
      @include -rg-BreakpointClasses($columns, $spacing, $visibility, $layout);
    }
    @else {
      @include rg-from($columns) {
        @include -rg-BreakpointClasses($columns, $spacing, $visibility, $layout);
      }
    }
  }
}

Modules/Packages

Sharing Sass code is becoming more important. Without the use of a proper module system in Sass we need to establish a few rules so that sharing code is consistent and behaviour is predictable. Sass packages are popping up in Bower and Github but there is no consistency in the way they are implemented.

A few general rules:

File Structure

Example structure:

/module-name
  /assets
    /fonts
    /images
  /components
    /responsive-grid
    /clearfix
    /animation
  /local
    /homepage
  /lib
    /mixins
    /functions
  bower.json
  index.scss

Namespacing

Module Entry Point

Package Management

Load Paths

Dependencies

As every module does not output anything just by being imported, packages can safely import other packages without the fear that a file has already been imported. Because of this, dependencies can safely require their own dependencies.

For example, a Grid package depends on a Clearfix package, but so does the LayoutHelpers package. Both of these packages can @import "clearfix/index" without fear that there will be two .clearfix classes in the output.

It is assumed that the components directory is added as a load path, so packages can easily require their dependencies.

Definitions

Object

A single piece of the design, usually fairly small. This could be things like .message, .block, .list, .post. Objects should be independent. Think of them as lego blocks. Objects have "modifiers" and "children".

Children

If an "object" is the parent, any sub-parts of that object are considered its children. Children are only ever controlled by the object it belongs to. A .message object may have a title that it styles, .message__title, this would be referred to as a child element.

Module

A single piece of functionality that can be composed of CSS, mixins, functions and assets (such as images or fonts). A module has a single entry point and a single purpose and role. eg. A grid framework could be a module.

Package

When a module is shared with others via a package manager like Bower it will generally be referred to as a package. This means that the term "module" and "packages" are fairly interchangable.

Block

This is another term for the concept of an "object".

Element

When referring to "objects" and "blocks", the word "element" is interchangable with the word "children".

Modifier

"Objects" may be modified in a way that changes their style in small ways, think of them as themes or alternative styles. For example, a .list object may have a .list--small modifier to make the text smaller.