CSS Codin’ Style

This document only defines style and formatting rules for writing CSS documents. It’s based on personal preferences and doesn’t pretend to be the “one and only” way of doing it.

Whitespace

Use Unix newline character: LF.
Use two spaces per indentation level.
Remove all trailing whitespace.
Always end files with a newline.
Use only one blank line as a separator.

Psst, you may want to check my [presentation about whitespace] (http://speakerdeck.com/battaglr/why-you-should-care-about-whitespace).

Rules

Place the opening brace next to the selector.
Use one space before the opening brace.
Define one declaration per line.
Place one space after the colon.
Always end declarations with a semicolon.
No space before a semicolon.
Place the closing brace in the same column as the first character of a rule.
Separate each rule by a blank line.

.button {
  font-size: .875rem;
}

.button--primary {
  color: #fff;
  background: #001f3f;
}

.button--secondary {
  color: #111;
  background: #aaa;
}

In large blocks of rules that only consist of one selector and one declaration, a single-line format should be used.

Use one space after the opening brace.
Use one space before the closing brace.
Don’t separate rules by a blank line.

.icon--anchor { background-image: url('assets/icons/anchor.svg'); }
.icon--bell { background-image: url('assets/icons/bell.svg'); }
.icon--cloud { background-image: url('assets/icons/cloud.svg'); }

Selectors

One selector per line in grouped selectors.

.button:hover,
.button:active {
  box-shadow: inset 0 0 .375em rgba(17, 17, 17, .6);
}

Quote attribute values using single quotes.

input[type='text'] {
  padding: .75em;
}

Use double colon notation in pseudo-elements.

.tooltip::after {
  content: attr(data-tooltip);
}

Values

Don’t specify length units for zero values.

.panel {
  margin: 0 0 2em;
}

Don’t specify leading nor trailing zeros in fractional numbers.

.offset {
  top: .25em;
  left: -.625em;
}

Include a space after each comma in comma-separated values.

body {
  font-family: Arial, Helvetica, sans-serif;
  color: rgb(17, 17, 17);
}

Long comma-separated set of values should be arranged across multiple lines.

Place the first set in the same line than the property.
Place the following set/s in a newline using one extra level of indentation.

.foobar {
  box-shadow: inset 0 0 .375em rgba(17, 17, 17, .6),
    0 0 .75em rgba(0, 0, 0, .6);
  background-image: url('assets/images/foo.png'),
    url('assets/images/bar.png');
}

Quote URL values using single quotes.

.cover {
  background: url('assets/images/cover.png');
}

Quote font family names that contain whitespace using single quotes.

.newspaper {
  font-family: 'Times New Roman', Times, serif;
}

Don’t place spaces before the opening parenthesis nor after the closing parenthesis of a function.

.column {
  width: calc(20% - .625em);
}

Don’t use keyword values when the same result could be achieved using an explicit value.

/* DON'T */
.panel {
  background-color: white;
  border-width: medium;
}

/* DO */
.panel {
  background-color: #fff;
  border-width: .25em;
}

Use lowercase for hexadecimal values, and shorthand notation when allowed.

/* DON'T */
.panel {
  background: #ffffff;
  border-color: #F3F3F3;
}

/* DO */
.panel {
  color: #111;
}

At-rules

At-rules that directly contain declarations should follow the same pattern that applies to any other rule.

@font-face {
  font-family: Boldy;
  font-style: normal;
  font-weight: 700;
  src: local('Boldy'),
    url('assets/webfonts/boldy.woff') format('woff');
}

Nested rules inside at-rules should be properly indented.

Don’t leave a blank line before the first rule.
Don’t leave a blank line after the last rule.

@media print {
  body {
    color: #000;
    background: transparent;
  }

  .sidebar {
    display: none;
  }
}

Comments

Use sentence case for all kind of comments.

/* Single-line comment. */

/**
 * Multi-line comment.
 */

Use native single-line comments when working with a transpiler.

// Single-line comment.

////
// Multi-line comment.
//

Tag comments

The only accepted tag is: TODO.
Use uppercase for the tag name.
Place a colon after the end of the tag name.
Place a space after the colon.

.panel {
  /* TODO: refactor `px` to `em`. */
  padding: 20px;
}

Section comments

When appropriate, break code into meaningful sections.

/* First level
   ---------------------------------------------------------------- */

/* Second level
   -------------------------------------------- */