This is an old version of this page. You can view the most recent version or browse the history.

css and sass coding standards

CSS + Sass

REMEMBER - If in doubt when deciding upon a style use existing, common patterns.

This guide borrows from practices demonstrated in Nicolas Gallagher's Idiomatic CSS.

1. Whitespace

Never mix spaces and tabs for indentation.
Use spaces for indenting and (4) space characters for each indentation level.

Tip: configure your editor to "show invisibles" or to automatically remove end-of-line whitespace.

Tip: use an EditorConfig file (or equivalent) to help maintain the basic whitespace conventions that have been agreed for your code-base.

2. Comments

Comment style should be simple and consistent within a single code base.

Place comments on a new line above their subject.
Keep line-length to a sensible maximum, e.g., 80 columns.
Make liberal use of comments to break CSS code into discrete sections.
Use "sentence case" comments and consistent text indentation.

Tip: configure your editor to provide you with shortcuts to output agreed-upon comment patterns.

CSS Example:

/* ==========================================================================
   Section comment block
   ========================================================================== */

/* Sub-section comment block
   ========================================================================== */

/**
 * Short description using Doxygen-style comment format
 *
 * The long description is ideal for more detailed explanations and
 * documentation. It can include example HTML, URLs, or any other information
 * that is deemed necessary or useful.
 *
 * TODO: This is a todo statement that describes an atomic task to be completed
 *       at a later date. It wraps after 80 characters and following lines are
 *       indented into a block.
 */

/* Basic comment */

Sass Example:

For Sass, double-slash comments should be used instead

// =============================================================================
// Section comment block
// =============================================================================


// Sub-section comment block
// =============================================================================


// Short description using Doxygen-style comment format
//
// The long description is ideal for more detailed explanations and
// documentation. It can include example HTML, URLs, or any other information
// that is deemed necessary or useful.
//
// TODO: This is a todo statement that describes an atomic task to be completed
//       at a later date. It wraps after 80 characters and following lines are
//       indented into a block.


// Basic comment

3. Format

Use one discrete selector per line in multi-selector rulesets.
Include a single space before the opening brace of a ruleset.
Include one declaration per line in a declaration block.
Use one level of indentation for each declaration.
Include a single space after the colon of a declaration.
Use lowercase and shorthand hex values, e.g., #aaa.
Use single or double quotes consistently. Preference is for double quotes, e.g., content: "".
Quote attribute values in selectors, e.g., input[type="checkbox"].
Where allowed, avoid specifying units for zero-values, e.g., margin: 0.
Include a space after each comma in comma-separated property or function values.
Include a semi-colon at the end of the last declaration in a declaration block.
Place the closing brace of a ruleset in the same column as the first character of the ruleset.
Separate each ruleset by a blank line.
Separate each Section comment block and Sub-section comment block by 4 lines (see practical example section below)

.selector-1,
.selector-2,
.selector-3[type="text"] {
    -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));
}

.selector-a,
.selector-b {
    padding: 10px;
}

Exceptions and slight deviations

Large blocks of single declarations can use a slightly different, single-line format. In this case, a space should be included after the opening brace and before the closing brace.

.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }

You can align a declarations block containing multiple property-value pairs by the colon for readability. If you format your declaration block this way, you must have at least one space before each colon, at only one space after each colon.

.selector-1 {
    display     : block;
    font-family : helvetica, arial, sans-serif;
    color       : #333;
    background  : #fff;
}

Long, comma-separated property values - such as collections of gradients or shadows - can be arranged across multiple lines in an effort to improve readability and produce more useful diffs. There are various formats that could be used; one example is shown below.

.selector {
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
}

Sass-specific

Limit nesting to 2 levels deep. Reassess any nesting more than 2 levels deep. This prevents overly-specific CSS selectors.
Always place @extend statements on the first lines of a declaration block.
Where possible, group @include statements at the top of a declaration block, after any @extend statements.

.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: 20em;
    // other declarations
}

4. Practical example

An example of various conventions.

// ==========================================================================
// Grid layout
// ==========================================================================
//
// Column layout with horizontal scroll.
//
// This creates a single row of full-height, non-wrapping columns that can
// be browsed horizontally within their parent.
//
// Example HTML:
//
// <div class="grid">
//     <div class="cell cell-3"></div>
//     <div class="cell cell-3"></div>
//     <div class="cell cell-3"></div>
// </div>




// Grid container
//
// Must only contain `.cell` children.
.grid {
    height      : 100%;
    font-size   : 0;
    white-space : nowrap;
}

// Grid cells
//
// No explicit width by default. Extend with `.cell-n` classes.
.cell {
    position       : relative;
    display        : inline-block;
    overflow       : hidden;
    box-sizing     : border-box;
    height         : 100%;
    padding        : 0 10px;
    border         : 2px solid #333;
    vertical-align : top;
    white-space    : normal;
    font-size      : 16px;
}

// Cell states
.cell.is-animating {
    background-color: #fffdec;
}




// Cell dimensions
// ==========================================================================

.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }





// Cell modifiers
// ==========================================================================

.cell--detail,
.cell--important {
    border-width: 4px;
}