Code Guide

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 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.
• Comma-separated property values should include a space after each comma (e.g. box-shadow).
• 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).
• Lowercase all hex values, e.g. #ccc.
• Use shorthand hex values where available, e.g. #ccc instead of #cccccc.
• Use the color names white and black instead of their hex counterparts: #fff and #000. For all other colors, use hex codes rather than color names.
• 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;.
• Use single quotes (') rather than double quotes (") in attribute selectors and properties. Do not use quotes in URI properties (url()). Exception: the @charset rule requires double quotation marks.

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

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.

Class and ID names

• Keep classes and IDs in lower spine-case (not snake_case or camelCase).
• Keep classes as short and succinct as possible, but avoid excessive and arbitrary shorthand notation. .btn is recognizable as button, but .s doesn't mean anything.
• Use meaningful names and avoid purely presentational ones; the latter is a sign of laziness and sloppy code.
• Do not use special prefixes like .e-* or .js-* to indicate an element as a target of behavior (as opposed to style). More often than not they're just doubling up on something that already has a meaningful name and only serve to make your code harder to read.

These rules also apply when creating Sass and Less variable names.

Declaration order

Related property declarations should be grouped together following the order:

1. Layout
2. Positioning
3. Box model
4. Visual
5. Typography
6. Content & animations

Layout and positioning come first because they 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.

For a complete list of properties and their order, please see my stylelint-order^† config.

^† stylelint-order is a plugin to the popular style linter stylelint, that enables you to check the order of your style declarations.

White space

Use white space (newlines) to enhance readability:

1. Between groups of property declarations as described in Declaration order
2. Between a property declaration and a nested ruleset
3. Between consecutive rulesets

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. (@import is okay in this case)
• Concatenate your CSS files with features provided in Rails, Jekyll, and other environments

For more information, read this article by Steve Souders.

NEVER USE !important. I MEAN IT.

• There is precisely one legitimate use of !important: when you need to override a style and you don't have access to the stylesheet in which it is defined, and therefore no inkling as to its specificity.
• If you are trying to override a style in your own code base, do not use !important. It's an admission of failure, as well as the opening shot in a (thermonuclear) war of specificity against yourself.
• CI builds will be configured to fail on use of !important.

In short, don't do it.

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. Here's a typical setup.

Prefixed properties

Don't use vendor prefixes in your CSS:

• They make your code hard to read.
• Browser support for experimental properties changes, in general, faster than you revisit vendor-prefixed CSS you’ve already written.

Instead, write your code without vendor prefixes and use a plugin like autoprefixer in your build pipeline.

Single declarations

In instances where a rule set includes only one declaration, keep the line breaks for better readability; your declarations will begin in the same column and be easier to scan.

Shorthand notation

Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. Commonly overused shorthand properties include:

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

Oftentimes we don't need to set all the values a shorthand property represents. For example, HTML headings only set top and bottom margin, so when necessary, only override those two values. Excessive use of shorthand properties often leads to sloppier code with unnecessary overrides and unintended side effects.

That said, there is no denying that using shorthand properties is convenient. The rule here is to use judgement and avoid overzealously using shorthand properties, especially if you know you'll need to override them in part later.

The Mozilla Developer Network has a great article on shorthand properties for those unfamiliar with notation and behavior.

Selectors

• Keep selectors short and strive to limit the number of elements in each selector to three; a shorter selector is a more performant selector, and helps to keep you from getting into a specificity war with yourself.
• Use classes over generic element tags for optimum rendering performance.
• Avoid using several attribute selectors (e.g. [class^='…']) on commonly occurring components. Browser performance is known to be impacted by these.
• Scope classes to the closest parent only when necessary (see Nesting below).

Nesting in Less and Sass

Avoid unnecessary nesting. Just because you can nest doesn't mean you should. Consider nesting only if you must scope styles to a parent and if there are multiple elements to be nested. The consequence is needlessly long, less performant, overly specific selectors.

Also take care with &, the parent selector:

• Avoid un-nesting with & (placing it at the end of a nested selector). It's confusing as hell and often has unintended consequences.
• Conversely, the parent selector is well-suited to defining styles for pseudo-classes and pseudo-elements.

Operators in Less and Sass

For improved readability, wrap all math operations in parentheses with a single space between values, variables, and operators. Take special care to do this for shorthand properties.

Colors in Less and Sass

Don't ever use raw hex colors in Less and Sass. Define them with human-readable variable names and use those. Better yet, assign colors to variables indicating their semantic usage.

Using semantic color variables throughout your code is more readable and easier to change.

Organization

• Organize sections of code by component/feature or page.
• Develop a consistent commenting hierarchy.
• Use consistent white space to your advantage when separating sections of code for scanning larger documents.
• When using multiple CSS files, bias toward breaking them down by component instead of page. Pages can be rearranged and components moved.

An example file hierarchy:

basics/
├── _colors.scss
├── _typography.scss
└── _grid.scss
shared/
├── _foundation.scss
├── _forms.scss
├── _mixins.scss
├── _header.scss
├── _footer.scss
└── _nav.scss
_feature-1.scss
feature-2/
├── _sub-feature-a.scss
└── _sub-feature-b.scss
_feature-3.scss