README.md

Principles of writing consistent, idiomatic CSS

The following document outlines a reasonable style guide for CSS development.
These guidelines strongly encourage the use of existing, common, sensible
patterns. They should be adapted as needed to create your own style guide.

This is a living document and new ideas are always welcome. Please
contribute.

Table of contents

1. General principles

"Part of being a good steward to a successful project is realizing that
writing code for yourself is a Bad Idea™. If thousands of people are using
your code, then write your code for maximum clarity, not your personal
preference of how to get clever within the spec." - Idan Gazit

Tip: use an EditorConfig file (or equivalent) to
help maintain the basic whitespace conventions that have been agreed for your
code-base.

3. Comments

Well commented code is extremely important. Take time to describe components,
how they work, their limitations, and the way they are constructed. Don't leave
others in the team guessing as to the purpose of uncommon or non-obvious
code.

Comment style should be simple and consistent within a single code base.

Place comments on a new line above their subject.

Keep line-length to a sensible maximum, e.g., 80 columns.

Make liberal use of comments to break CSS code into discrete sections.

/* ========================================================================== Section comment block ========================================================================== *//* Sub-section comment block ========================================================================== *//** * Short description using Doxygen-style comment format * * The first sentence of the long description starts here and continues on this * line for a while finally concluding here at the end of this paragraph. * * The long description is ideal for more detailed explanations and * documentation. It can include example HTML, URLs, or any other information * that is deemed necessary or useful. * * @tag This is a tag named 'tag' * * TODO: This is a todo statement that describes an atomic task to be completed * at a later date. It wraps after 80 characters and following lines are * indented by 2 spaces. *//* Basic comment */

4. Format

The chosen code format must ensure that code is: easy to read; easy to clearly
comment; minimizes the chance of accidentally introducing errors; and results
in useful diffs and blames.

Use one discrete selector per line in multi-selector rulesets.

Include a single space before the opening brace of a ruleset.

Include one declaration per line in a declaration block.

Use one level of indentation for each declaration.

Include a single space after the colon of a declaration.

Use lowercase and shorthand hex values, e.g., #aaa.

Use single or double quotes consistently. Preference is for double quotes,
e.g., content: "".

Long, comma-separated property values - such as collections of gradients or
shadows - can be arranged across multiple lines in an effort to improve
readability and produce more useful diffs. There are various formats that could
be used; one example is shown below.

Preprocessors: additional format considerations

Different CSS preprocessors have different features, functionality, and syntax.
Your conventions should be extended to accommodate the particularities of any
preprocessor in use. The following guidelines are in reference to Sass.