CSS Guidelines

Partially Inspired by http://codeguide.co/

Golden rule

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

Syntax

• Use hard tabs with two spaces. They're faster, cleaner and less prone to accidental misalignment.
• When grouping selectors, keep individual selectors to a single line.
• 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. The last declaration's is optional, but your code is more error prone without it.
• Don't include spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values. This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).
• Don't prefix property values or color parameters with a leading zero (e.g., .5 instead of 0.5 and -.5px instead of -0.5px).
• Lowercase all hex values, e.g., #fff. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.
• Use shorthand hex values where available, e.g., #fff instead of #ffffff.
• Quote attribute values in selectors, e.g., input[type="text"]. They're only optional in some cases, and it's a good practice for consistency.
• Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.

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

Declaration Order

Sort your declarations alphabetically to make it easy to read and avoid duplicate entries. Use F9 in Sublime Text to sort selected text alphabetically.

Don't Use @import

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:

• Use multiple <link> elements
• Compile your CSS with a preprocessor like Sass or Less into a single file
• Concatenate your CSS files with features provided in Rails, Jekyll, and other environments

For more information, read this article by Steve Souders.

Media query placement

Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future.

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

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

Single declarations

In instances where a rule set includes only one declaration, consider removing line breaks for readability and faster editing. Any rule set with multiple declarations should be split to separate lines.

The key factor here is error detection-e.g., a CSS validator stating you have a syntax error on Line 183. With a single declaration, there's no missing it. With multiple declarations, separate lines is a must for your sanity.

/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.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; }

Nesting with LESS

Nesting makes CSS cleaner and easier to read, and lessens the need to write duplicate selectors. It also allows collapsing sections in your code editor to hide what you don't need to see.

Keep in mind nesting will increase your specificity, overriding less specific CSS.

#sidebar {
	background: white;
	width: 220px;
	#section {
		color: red;
		width: 100px;
	}
	table {
		background: orange;
		width: 100%;
	}
}

Comments

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. Do not simply reiterate a component or class name.

Be sure to write in complete sentences for larger comments and succinct phrases for general notes. For elaborate features and components we can document in this coding guide.

You can use double forward slash (//) to write comments in LESS.

Class names

• Keep classes lowercase and use dashes (not underscores or camelCase). Dashes serve as natural breaks in related class (e.g., .btn and .btn-danger).
• 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.
• Use meaningful names; use structural or purposeful names over presentational.
• Prefix classes based on the closest parent or base class.
• Use .js-* classes to denote behavior (as opposed to style), but keep these classes out of your CSS.

It's also useful to apply many of these same rules when creating Sass and Less variable names.

/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selectors

• Use classes over generic element tag for optimum rendering performance. Specific often means speed.
• Avoid using several attribute selectors (e.g., [class^="..."]) on commonly occuring components. Browser performance is known to be impacted by these.
• Keep selectors short and strive to limit the number of elements in each selector to three.
• Scope classes to the closest parent only when necessary (e.g., when not using prefixed classes).

Additional reading:

• Scope CSS classes with prefixes
• Stop the cascade

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

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Writing-CSS