Introduction

The CSS style guide in use at Procurios is based on various sources and experiences in the past few years. Most of it is based on our own experience with maintaining a large codebase. An important source of inspiration is Harry Roberts, who published his work on cssguidelin.es. Another inspiring source is Code Guide, by @mdo.

Rules (anatomy and syntax)

A CSS rule is built out of the following blocks:

[selector] {
[property]: [value];
}

The combination of a property and a value is called a declaration.
A typical CSS rule based on this style guide looks as following:

Place the first declaration on a new line after the opening brace

Limit line length to 80 characters

Where possible, limit the length of a line to a maximum of 80 characters.

/** * This comment explains the following CSS in detail. A little bit too many * details, because the length of one line exceeds 120 characters. Hence, * it's carefully broken into pieces to enhance readability.*/

There will be unavoidable exceptions to this rule (fe. URLs, gradient syntax).

Naming conventions

Selectors

Poor Selector Intent is one of the biggest reasons for headaches on CSS projects. Writing rules that are far too greedy—and that apply very specific treatments via very far reaching selectors—causes unexpected side effects and leads to very tangled stylesheets, with selectors overstepping their intentions and impacting and interfering with otherwise unrelated rulesets.

CSS cannot be encapsulated, it is inherently leaky, but we can mitigate some of these effects by not writing such globally-operating selectors: your selectors should be as explicit and well reasoned as your reason for wanting to select something.

Use classes to select elements

The reasoning behind using only classnames to select elements:

The CSS is decoupled: The dependency on the DOM is kept to a minimum. It makes it much easier to move your CSS around.

The CSS is isolated: Classnames based on our naming convention are scoped to a specific Block.

The CSS is descriptive: Classnames based on our naming convention tell developers stuff about what they're styling.

/** bad */headerul {
...
}
/** good */.siteNav {
...
}

Don't worry about unavoidable exceptions to this rule. Use it as a rule of thumb.

Use the least number of selectors required to style an element

Use !important with care

The general rule is that !important is always a bad thing, but all rules have exceptions. Harry Roberts makes a distinction between proactive and reactive use of !important.

Proactive use of !important is when it is used before you’ve encountered any specificity problems; when it is used as a guarantee rather than as a fix. For example:

.one-half {
width: 50%!important;
}

Reactive use of !important is when it is used to combat specificity problems. In these situations, it is preferable that you investigate and refactor any offending rulesets to try and bring specificity down across the board.

Media queries

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.

Here's a simple example: Say you have an element which is normally 100px wide, but it uses an EQ to say that if its container is less than 200px wide, the element becomes 500px wide. (This is silly, but bear with me.) If the container is explicitly sized (width: 150px; or the like), this is fine, but if the container is sized to its contents (float: left;, for example), then you have a circular dependency: if the element is 100px wide, the container is 100px wide, but that trigger the EQ, so the element is 500px wide, so the container is 500px wide, but that disables the EQ, so the element is 100px wide, so the container is 100px wide, etc.

In other words: browser vendors have some fundamental issues to deal with before EQs are shipped as native feature. Tab ends his overview with:

So that's the state of Element Queries in 2014. We're not really any closer to having them than we were in 2013, but there's light on the horizon for a possible good solution.