CSS Code Guide

Every line of code should appear to be written by a single person, no matter the number of contributors.

---

Table of contents

• Syntax
• Editor Preferences
• CSS Validity
• Declaration Order
• Media Query Placement
• Shorthand Notation
• Comments
• Selectors
• ID and Class Naming

---

Purpose

• Strive to maintain CSS standards and semantics, but not at the expense of practicality.

Using CSS according to its purpose is important for accessibility, reuse, and code efficiency reasons.

---

Syntax top

• Include one space before the opening brace of declaration blocks for legibility.
• Place closing braces of declaration blocks on a new line.
• Include one space after : for each declaration.
• Each declaration should appear on its own line for more accurate error reporting.
• End all declarations with a semi-colon.
• Put a blank line between rules.
• Use single quotation marks for attribute selectors and property values.
• Comma-separated property values should include a space after each comma (e.g., box-shadow).
• Lowercase all hex values, e.g., #fff.
• Use shorthand hex values where available, e.g., #fff instead of #ffffff.
• Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.

/* Not recommended */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Recommended */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0, 0, 0, 0.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

---

Editor Preferences top

• Use soft-tabes set to four spaces.
• Trim trailing white space on save.
• Set encoding to UTF-8.
• Add new line at end of files.

---

CSS Validity top

Use a linter or tools such as the W3C CSS validator to test.

Using valid CSS is a measurable baseline quality attribute that allows to spot CSS code that may not have any effect and can be removed, and that ensures proper CSS usage.

---

Declaration Order top

Related property should be grouped together following the order:

1. Positioning
2. Box model
3. Typographic
4. Visual

Positioning comes first because it can remove an element from the normal flow of the document and override box model related styles.

The box model comes next as it dictates a component's dimensions and placement.

Everything else takes place inside the component or without impacting the previous two sections, and thus they come last.

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

---

Media Query Placement top

Place media queries as close to their relevant rule sets or component whenever possible.

Don't bundle them all in a separate stylesheet.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

---

Shorthand Notation top

Use shorthand properties where possible. Common shorthand properties include:

• padding
• margin
• font
• background
• border
• border-radius

Using shorthand properties is useful for code efficiency and understandability.

/* Not recommended */
.element {
    border-top-style: none;
    font-family: palatino, georgia, serif;
    font-size: 100%;
    line-height: 1.6;
    padding-bottom: 2em;
    padding-left: 1em;
    padding-right: 1em;
    padding-top: 0;
}

/* Recommended */
.element {
    border-top: 0;
    font: 100%/1.6 palatino, georgia, serif;
    padding: 0 1em 2em;
}

---

Comments top

Kill the comments.

/* Not recommended */
/* Modal header */
.modal-header {
  ...
}

/* Recommended */
.modal-header {
  ...
}

---

Selectors top

Use classes over generic element tag for optimum rendering performance.

Scope classes to the closest parent only when necessary (when not using prefixed classes).

/* Not recommended */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Recommended */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Avoiding unnecessary ancestor selectors is useful for performance reasons.

/* Not recommended */
ul#example {}
div.error {}

/* Recommended */
#example {}
.error {}

---

ID and Class Naming top

• Keep classes lowercase and use dashes as they are natural breaks in related class.
• Avoid excessive and arbitrary shorthand notation. .btn is useful for button, but .s doesn't mean anything.
• Keep classes as short and succinct as possible.
• Instead of presentational or cryptic names, always use ID and class names that reflect the purpose of the element in question, or that are otherwise generic.
• Using functional or generic names reduces the probability of unnecessary document or template changes.

/* Not recommended: meaningless */
#yee-1901 {}

/* Not recommended: presentational */
.button-green {}
.clear {}

/* Recommended: specific */
#gallery {}
#login {}
.video {}

/* Recommended: generic */
.aux {}
.alt {}