Standards for developing flexible, durable, and sustainable HTML and CSS.
- Golden rule
- HTML
- Syntax
- HTML5 doctype
- Pragmatism over semantics
- Attribute order
- [JavaScript generated markup](#javascript-generated markup)
- CSS
- Writing copy
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.
- 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>Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.
<!DOCTYPE html>Strive to maintain HTML standards and semantics, but don't sacrifice pragmatism. Use the least amount of markup with the fewest intricacies whenever possible.
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>Writing markup in a javascript file makes the content harder to find, harder to edit, and less performant. Don't do it.
- 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.,
#fffinstead of#FFF - Use shorthand hex values where available, e.g.,
#fffinstead of#ffffff - Quote attribute values in selectors, e.g.,
input[type="text"] - Avoid specifying units for zero values, e.g.,
margin: 0;instead ofmargin: 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.
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.
In some cases, it makes sense to deviate slightly from the default syntax.
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 (⌃⇧↓).
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; }Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.
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 {
...
}- 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 { ... }- 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 { ... }- Organize sections of code by component
- Develop a consistent commenting hierarchy
- If using multiple CSS files, break them down by component
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.
Heavily inspired by Idiomatic CSS and the GitHub Styleguide. Made with all the love in the world by @mdo.