SCSS Style Guide

Specificity

Keep CSS rules as flat as possible. Add specificity globally as needed to override central styles.

#{$specify} .foo

Use quasi-qualifiers where possible to indicate where a class is expected to be used.

/*.foo*/.bar

instead of

.foo .bar

If selecting an id is necessary, do so with an attribute value selector.

[id="foo"]

Style

Use 2 spaces to indent, or soft tabs set to 2 spaces. Always place a space between the selector and the opening bracket

.foo {}

Keep a "one change per line" practice - every selector and declaration should be on their own line unless there is only one selector AND one declaration. Always use a semicolon after every declaration.

.foo,
.bar {
  property: value;
  property: value;
}

.baz { property: value; }

Naming

Use hyphons to separate words in a name instead of underscores or camelCase. .foo-bar is good, .fooBar is bad.

Use semantic names for classes. Describe their purpose, not their use exact case or exact functionality. .footer-link is bad .secondary-link is good.

Whitespace

Thoughtful use of whitespace promotes faster readability. Use 1 blank new line between every rule, 3 between loosely related rules, and 5 between sections.

Comments

Keep comments at a maximum length of 80 characters.

Section

/* ==========================================================================
   # Section Title
========================================================================== */

/* Sub Section
-------------------------------------------------------------------------- */

Block comments

/**
 * Block comment description
 * [1] comment
 * [2] comment
**/

.foo {
  property: value; /*[1]*/
  property: value; /*[2]*/
}

Inline comments

Use inline comments to reference a single declaration or rule set

/* Inline comment addressing rule set */
.foo {
  ...
}

/* [1] Inline comment addressing declaration */
.foo {
  property: value; /*[1]*/
}

Comment Documentation

For Sass functions, mixins, and variables, you should document them using sassdoc style comments.

/// Description
/// @name Name of function
/// @group Group it belongs to (optional)
/// @author (optional)
/// 
/// @param {type} $name [default] - Description
/// @returns - Description
/// @example (optional)

Param types

{number(unit)} // where unit can be any css unit or "unitless"
{string}
{map}
{key(map)}
{color} // any valid css color unit
{keyword[array]} // where array is a comma separated list of accepted keywords
{boolean} // when accepted keywords are either "true" or "false"

Separate types with a pipe

{boolean | null}

Additional keys

In addition to the keys shown above, it can also be useful to use @see, @requires, and @deprecated

Table of contents

While it can be difficult to maintain a table of contents, it is extremely helpful when trying to find specific styles

/* --------------------------------------------------------------------------
[Table of contents]

GROUP
* SECTION NAME | _file.scss
* Sub Section.......................Description
* Sub Section.......................Description
*
* SECTION NAME | _file.scss
* Sub Section.......................Description

GROUP
* SECTION NAME | _file.scss
* Sub Section.......................Description
-------------------------------------------------------------------------- */

File Structure

src/
  js/
    _file.js
  scss/
    core/
      _functions.scss
      _mixins.scss
    base/
      _document.scss
      _typography.scss
      ...
    widgetkit/
      core/
        _grid.scss
      _wk-component.scss
    areas/
      _layout.scss
      _navigation.scss
      ...
  _config.scss
  style.scss
lib/
  scripts/
    scripts.js
  styles/
    style.css