/code-guide

Standards for developing flexible, durable, and sustainable HTML and CSS.

HTML and CSS code guide

Standards for developing flexible, durable, and sustainable HTML and CSS.

Table of contents

Golden rule

All code in any code base should look like a single person typed it, no matter how many people contributed.

This means strictly enforcing these agreed upon guidelines at all times. For additions or contributions, please file an issue on GitHub.

HTML

HTML syntax

  • Use soft-tabs with two spaces
  • Nested elements should be indented once (2 spaces)
  • Always use double quotes, never single quotes
  • Don't include a trailing slash in self-closing elements

Incorrect example:

<!DOCTYPE html>
<html>
<head>
<title>Page title</title>
</head>
<body>
<img src='images/company-logo.png' alt='Company' />
<h1 class='hello-world'>Hello, world!</h1>
</body>
</html>

Correct example:

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.

<!DOCTYPE html>

Pragmatism over semantics

Strive to maintain HTML standards and semantics, but don't sacrifice pragmatism. Use the least amount of markup with the fewest intricacies whenever possible.

Attribute order

HTML attributes should come in this particular order for easier reading of code.

  • class
  • id
  • data-*
  • for|type|href

Such that your markup looks like:

<a class="" id="" data-modal="" href="">Example link</a>

JavaScript generated markup

Writing markup in a javascript file makes the content harder to find, harder to edit, and less performant. Don't do it.

CSS

CSS syntax

  • Use soft-tabs with two spaces
  • When grouping selectors, keep individual selectors to a single line
  • Include one space before the opening brace of declaration blocks
  • Place closing braces of declaration blocks on a new line
  • Include one space after : in each property
  • Each declaration should appear on its own line
  • End all declarations with a semi-colon
  • Comma-separated values should include a space after each comma
  • Don't include spaces after commas in RGB or RGBa colors, and don't preface values with a leading zero
  • Lowercase all hex values, e.g., #fff instead of #FFF
  • Use shorthand hex values where available, e.g., #fff instead of #ffffff
  • Quote attribute values in selectors, e.g., input[type="text"]
  • Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;

Incorrect example:

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

Correct example:

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

Questions on the terms used here? See the syntax section of the Cascading Style Sheets article on Wikipedia.

Declaration order

Related declarations should be grouped together, placing positioning and box-model properties closest to the top, followed by typographic and visual properties.

.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;
}

For a complete list of properties and their order, please see Recess.

Formatting exceptions

In some cases, it makes sense to deviate slightly from the default syntax.

Prefixed properties

When using vendor prefixed properties, indent each property such that the value lines up vertically for easy multi-line editing.

.selector {
  -webkit-border-radius: 3px;
     -moz-border-radius: 3px;
          border-radius: 3px;
}

In Textmate, use Text → Edit Each Line in Selection (⌃⌘A). In Sublime Text 2, use Selection → Add Previous Line (⌃⇧↑) and Selection → Add Next Line (⌃⇧↓).

Rules with single declarations

In instances where several rules are present with only one declaration each, consider removing new line breaks for readability and faster editing.

.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Human readable

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.

Comments

Great code comments convey context or purpose and should not just reiterate a component or class name.

Bad example:

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

Good example:

/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Class names

  • Keep classes lowercase and use dashes (not underscores or camelCase)
  • Avoid arbitrary shorthand notation
  • Keep classes as short and succinct as possible
  • Use meaningful names; use structural or purposeful names over presentational
  • Prefix classes based on the closest parent component's base class

Bad example:

.t { ... }
.red { ... }
.header { ... }

Good example:

.tweet { ... }
.important { ... }
.tweet-header { ... }

Selectors

  • Use classes over generic element tags
  • Keep them short and limit the number of elements in each selector to three
  • Scope classes to the closest parent when necessary (e.g., when not using prefixed classes)

Bad example:

span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

Good example:

.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organization

  • Organize sections of code by component
  • Develop a consistent commenting hierarchy
  • If using multiple CSS files, break them down by component

Copy

Sentence case

Always write copy, including headings and code comments, in sentence case. In other words, aside from titles and proper nouns, only the first word should be capitalized.

Thanks

Heavily inspired by Idiomatic CSS and the GitHub Styleguide. Made with all the love in the world by @mdo.