SASS code standards

We follow the coding standards rules from the brilliant Code Guide by @mdo (which in turn was heavily inspired by Idiomatic CSS and the GitHub Styleguide) with a few exceptions as described below.

We use SASS Lint for SASS code linting and enforcement of syntax consistency. See our .sass-lint.yml for a detailed view.

Syntax & formatting

The following are exceptions or additions to @mdo’s Code Style:

Declaration order

Use this ordering of property declarations:

1. Extends
   (enforced with extends-before-declarations & extends-before-mixins rules)
2. Mixins
   (enforced with extends-before-mixins & mixins-before-declarations rule)
3. Style declarations (in alphabetical order - enforced by property-sort-order rule)
4. Media queries

For example:

.selector {
    @extend %something;
    @include font(1);
    background: red;
    color: blue;
    margin: 0 auto;

    @include mq($from: md) {
        color: orange;
    }
}

Prefixed properties

We encourage writing CSS as close to the W3C spec as possible which means not including vendor prefixes in our source. If these are needed for legacy browser support then we encourage use of tools like PostCSS Autoprefixer.

BEM and naming

There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.

We follow the class naming rules (and selector rules) from @mdo. However, it’s about CSS/SASS in general and doesn’t include anything specifc about BEM.

We encourage use of BEM because (from Airbnb’s CSS / Sass Styleguide):

• It helps create clear, strict relationships between CSS and HTML
• It helps us create reusable, composable components
• It allows for less nesting and lower specificity
• It helps in building scalable stylesheets

Variable naming

Variable names should follow the general-to-specific approach as suggested on SASS’s Code Style Guide.

$color-link;
$color-link-dark;
$color-link-light;

Comments

The other difference from @mdo’s Code Guide is comment style. We use SassDoc to auto-generate documentation from our comments, so we use SassDoc annotations and file-level annotations:

/// This is the description of a mixin
/// @param {Number} $some-vale A value that gets passed in
@mixin($some-value) {
    // Do something
}

SASS Documentation

Edit on GitHub