KISSmetrics Style Guides

 › CSS Styleguide

Table of Contents

• Coding-style
• CSS
  • Properties
  • Selectors
  • Shorthand
  • Classes
• SCSS
  • Nesting
  • Variables
  • Organization
• Comments
• Vendor Prefixes

Coding-style

• Use soft-tabs with a two space indent.
• Keep lines fewer than 80 characters.
• Never leave trailing whitespace.
• Avoid IDs in CSS.
• Do not restate default property & value combinations (for instance display: block; on block-level elements).
• Use US English for all naming. Name classes and variables in the locale of the language you are working with.

CSS

Properties

• Put spaces after : in property declarations.

# Bad
a {
  color:#F00;
}

# Good
a {
  color: #F00;
}

• Use hex or rgb for specifying color

# Bad
a {
  color: whitesmoke;
}

# Good
a {
  color: #F5F5F5;
}

• Sort properties based on type. Properties that affect document flow and element position take precedence

Tags that affect document flow include: position, display, top, margin

These tags affect more than just presentational content inside of their respective containers, and moving them to the top of their selector helps with readability.

# Bad
h1 {
  background-color: #333;
  left: 0;
  position: fixed;
  top: 0;
}

# Good
h1 {
  position: fixed;
  top: 0;
  left: 0;
  background-color: #333;
}

Selectors

• Avoid over-qualified selectors.

# Bad
div.container {}

# Good
.container {}

# Bad
ul.nav li a {}

# Good
.nav a {}

• Selector rules should consistently use newlines

# Bad
.selector { color: #444; }

# Good
.selector {
  color: #444;
}

• Each selector should be on its own line, ending in either a comma or an opening curly brace.

# Bad
.selector-1, .selector-2, .selector-3 {
  background: #fff;
  color: #000;
}

# Good
.selector-1,
.selector-2,
.selector-3 {
  background: #fff;
  color: #000;
}

Shorthand

Shorthand should be used within reason and caution.

• Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values as much as possible.

# Bad
div {
  margin-top: 10px;
  margin-right: 25px;
  margin-bottom: 10px;
  margin-left: 25px;
}

# Good
div {
  margin: 10px 25px;
}

Classes

When creating a class name, be semantic and label the function of the element you are naming. Using classes that aren't semantic only serves as a shortcut to writing inline CSS.

Bad class names: pink float-left align-center one-and-a-half xy

Good class names: sidebar post author cta description

A good rule of thumb to figure out if your class name makes sense is to look at the class names that lead up to it.

<article class='blog-post'>
  <header>
    <h1 class='title'>On the Shortness of Life</h1>
    <div class='author'>
      <h3 class='name'>Seneca</h3>
      <img src='...'>
    </div>
  </header>
  <div class='align-left'>
    The majority of mortals, Paulinus, complain bitterly...
  </div>
</article>

Here, it's easy to understand layout, even if you don't know what the text is. .blog-post .author .name reads very coherently illustrates the content inside. .blog-post .align-left doesn't give any indication of content. Don't use multiple classes as a way to skirt this principle.

SCSS

• Any $variable or @mixin that is used in more than one file should be put in globals/. Others should be put at the top of the file where they're used.
• As a rule of thumb, don't nest further than 3 levels deep. If you find yourself going further, think about reorganizing your rules (either the specificity needed, or the layout of the nesting).

Nesting

• Nested Selectors should always follow styles affecting the parent

# Bad
.post {

  header {
    background-color: #FFF;
  }

  width: 600px;
}

# Good
.post {
  width: 600px;

  header {
    background-color: #FFF;
  }
}

• Nested Selectors should always be preceded by a newline

# Bad
.post {
  width: 600px;
  header {}
}

# Good
.post {
  width: 600px;

  header {}
}

• Nested Selectors affecting the parent element should list before child selectors

# Bad
.post {

  header {}

  &:hover {}
}

# Good
.post {

  &:hover {}

  header {}
}

• Nested media queries should list above child selectors

# Bad
.post {

  header {}

  @media screen and (max-width: 640px) {}
}

# Good
.post {

  @media screen and (max-width: 640px) {}

  header {}
}

• Maximum Nesting should be no more than three levels deep

.post {

  header {

    nav {
      // no more!
    }
  }
}

Variables

Variables were created for a few reasons:

• They speed up the process of writing new CSS
• They make changing global and presentational properties of a page faster
• They enable the quick maintenance CSS by facilitating uniformity

Variables fall into two categories: globals and helpers.

Global variables are there to enforce the overarching themes present in a site. Background colors, font colors, typefaces, etc. They should be used with a consistent prefix such as base or primary to illustrate their relevance in a broad context.

Helper variables serve a different role. They are variables whose purpose fits into a niche context. Things like error styling, promotional styling, and CTAs can all use helper variables.

• Name the contents of the variable, not the element it is applied to when possible

# Bad
$baseBackgroundColor

# Good
$baseWhite

• Avoid variation in naming schemes for 'base' colors

# Bad
$primaryWhite
$baseBlue

# Good
$baseWhite
$baseBlue

• Font families should be named on function, not typeface

# Bad
$comicsans:       Comic Sans MS, sans-serif;
$papyrus:         Papyrus, fantasy;

# Good
$baseSansSerif:   'Open Sans', sans-serif;
$baseSerif:       'Open Serif', serif;

• When naming helper colors, the first word should describe usage and the color should always be mentioned

# Bad
$secondRed
$limeGreen
$ctaBackground

# Good
$errorRed
$successGreen
$ctaYellow

• Variable assignments should be organized by column when using a dedicated variable file

Variable files should not contain actionable css, only property assignments. As such, use a vertical column layout to make the page more readable.

# bad
$baseSansSerif: 'Open Sans', sans-serif;
$baseSerif: 'Open Serif', serif;

# Good
$baseSansSerif:   'Open Sans', sans-serif;
$baseSerif:       'Open Serif', serif;

Organization

File structure should marry the concept of atomic CSS with the best practices of the platform serving the application. Assuming a rails applicatons, consider a file structure like the following:

stylesheets
├── globals
│   ├── mixins.scss
│   └── variables.scss
├── atoms
│   ├── buttons.scss
│   ├── fields.scss
│   ├── headings.scss
│   ├── links.scss
│   └── paragraphs.scss
├── molecules
│   ├── articles.scss
│   ├── forms.scss
│   └── headers.scss
├── layouts
│   ├── fullwidth.scss
│   └── signupsidebar.scss
├── application.scss
└── home.scss

Comments

• Only comment where it is useful.
• Write comments like you’re talking to a rubber duck!
• Good comments take care of 99% of what you hand over and — more importantly —  take care of your documentation. Your code should be the documentation.
• CSS comments may be copied across to production. So be careful what you write.
• SCSS supports both comments that are preserved in the CSS output and comments that aren’t.
• In SCSS use /* comment description */ if you want a comment to be included in the processed CSS file. Use // if you do not want the comment to be included in the CSS file.

# Bad
/* Let's simplify this line before release */

# Good
// Causing an overflow bug in Firefox 23.0.1. Discussion at github.com

Vendor Prefixes

• Vendor prefixes should go longest (-webkit-) to shortest (unprefixed).
• Always specify the unprefixed property last.

# Bad
-webkit-box-shadow: inset 0 0 1px 1px #eee;
-moz-box-shadow: inset 0 0 1px 1px #eee;
box-shadow: inset 0 0 1px 1px #eee;

# Good
-webkit-box-shadow: inset 0 0 1px 1px #eee;
   -moz-box-shadow: inset 0 0 1px 1px #eee;
        box-shadow: inset 0 0 1px 1px #eee;

• Whenever possible, use vendor prefixes from a mixin file