CSS Style Guide

We have a few rules that we like to live by when writing CSS.

Use the Force, Luke.

All of the principles and ideas listed here are taken from different places and written by very smart people including the Github styleguide and Idiomatic CSS.

Our goal here is to make it easy for everyone to contribute clean, readable and sensible code.

General principles

  • Don't try to prematurely optimize your code; keep it readable and understandable.
  • All code in any code-base should look like a single person typed it, even when many people are contributing to it.
  • We're going to strictly enforce the agreed-upon style.
  • If in doubt when deciding upon a style, use existing, common patterns.

Whitespace

Only one style should exist across the entire source of your code base. Always be consistent in your use of whitespace. Use whitespace to improve readability.

  • Never mix spaces and tabs for indentation.
  • Use soft tabs with a 2 space indent ( Why we chose tabs over spaces).
  • Configure your editor to "show invisibles" or to automatically remove end-of-line whitespace.

Comments

Code that is commented well is extremely important. Take the time to describe components, how they work, their limitations, and the way they are constructed. Don't leave others in the team guessing as to the purpose of uncommon or unobvious code.

Comment style should be simple and consistent.

  • Place comments on a new line above their subject.
  • Keep line length to a sensible maximum (don't make others scroll horizontally to read your comments).
  • Make liberal use of comments to break CSS code in to discrete sections.
  • Use "sentence case" comments and consistent text indentation.
/* ==========================================================================
   Section comment block
   ========================================================================== */


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


/**
* Short description using Doxygen-style comment format
*
* The first sentence of the long description starts here and continues on this
* line for a while finally concluding here at the end of this paragraph.
*
* 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.
*
* @tag This is a tag named 'tag'
*
* 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 by 2 spaces.
*/


/* Basic comment */

Format

The chosen code format ensures that the code is easy to read, easy to clearly comment, minimizes the chance of accidentally introducing errors and results in useful diffs.

  • Use one descrete selector per line in multi-selector rulesets.
  • Put spaces after : in property declarations.
  • Put spaces before { in rule declarations.
  • Use hex color codes #000 unless you're using rgba. Use hex short codes when they're available.
  • For the sake of simplicity, organize your properties alphabetically.
  • Use double quotes; for example, content: "".
  • Use quote attribute values in selectors; for example, input[type="checkbox"].
  • Where allowed, avoid specifying units for zero-values; for example margin: 0.
  • Include a space after each comma in comma-separated property or function values.
  • Include a semicolon at the end of each property declaration.
  • 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.
  • If using vendor-specific properties, make sure the W3C version of the property comes last.
  • Use a - for separating compound class names.
.selector-1,
.selector-2,
.selector-3[type="text"] {
  background: #fff;
  background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
  color: #333;
  display: block;
  font-family: helvetica, arial, sans-serif;
}


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

Rems

Since our patterns are built on Zurb Foundation, we use rem for font-size. Additionally, unit-less line-height is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the font-size.

Specificity (classes vs. IDs)

Elements that occur exactly once inside a page should use IDs, otherwise, use classes. When in doubt, use a class name.

  • Good candidates for IDs: header, footer, modal popups.
  • Bad candidates for IDs: navigation, item listings, item view pages.
  • If you must use an ID selector #selector, make sure that you have no more than one in your rule declaration. A rule like #header .search #quicksearch { ... } is considered harmful.