Code standards: CSS

The status of this document is currently Request for Comments.

The following is our set of style guidelines for writing CSS.

1. Preprocessor

We use SCSS to compile CSS. The source files should be structured like this:

• Primary files are standalone and have a filename consisting of one (generally preferable) or multiple words (if appropriate - separated by hyphens), ending with the ".scss" file extension.
  Examples: codidact.scss, material-design-lite-grid.scss.
• Secondary files are included in primary files and cannot exist on their own. Their filename starts with an underscore, and then follow the same rules as primary files: one or more words (separated by hyphens), ending with the extension ".scss".
  Examples: _question-list.scss, _icon-toggle.scss.

Primary files must not be included in other primary or secondary files.

Variables are SCSS variables (evaluated at compile time), unless they are community-specific (such as primary color). These are CSS variables (--name, var(--name)) and evaluated at run time.

CSS must be minified after compilation. (TODO: *node-sass has the --output-style compressed option, right?)

2. Naming

Please refer to the following document, which shall be part of this standard: Code standards: CSS naming

3. Order of selectors

Universal selectors must appear first, followed by type (tag) selectors. An extra blank line should separate these from class, attribute and ID selectors, which in turn can appear in any order.

Selectors (and rules in general) should preferably be added to the CSS stylesheets in the same order in which they appear in the markup files (.html, .cshtml and equivalent).

Within stylesheets, the order of selectors should be consistent (i.e. in the global scope as well as within @media selectors).

Pseudo-classes and pseudo-element selectors should appear after the main selector if it exists.

@media and other nested at-rules should be added to the end of the document, preceded by an extra blank line.

See landing-page/primary.css @1ca2f671 for an example of all of the above.

4. Spacing

• Code should be indented with four spaces. Do not use tab stops.
• Rules must be separated by a blank line between them.
• Do not write more than one statement per line.

5. Line breaks

Rules should be separated by a blank line, except for the two special cases provided in item #3 - namely, an extra blank line is expected between universal selectors and other selectors, as well as before nested at-rules. As such, these rule groups should be separated by two spaces.

All properties are written on their own line and end with a semicolon. The closing bracket must appear in its own line.

When multiple selectors are part of the same rule, each selector must appear in a separate line and must be followed by a comma, except for the last selector which shall contain the opening bracket ({) for the CSS rule as usual.

.red, 
.has-color-red,
.this-color-is-really-red {
    color: #f00;
}

An exception is applied: For the combination of a single CSS selector and a single property, the entire rule can (but does not must) be written in one line, with spaces surrounding the property within braces:

#load-overlay { display: none; }

Comments must be preceded by a newline, but need not be followed by one.

6. Shorthand properties

Do not use shorthand properties.
Prefer:

font-style: bold;
font-size: 2em;
font-family: "Verdana", "Arial", sans-serif;

over font: bold 2em "Verdana", "Arial", sans-serif;.

7. Quotes

Always prefer double quotes.

Always enclose non-generic typeface identifiers in quotes. Generic font-family identifiers must not be enclosed in quotes, according to the relevant W3C rule.
Example:

font-family: "Open Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif;

8. Line length

Please limit line length to 120 characters or less.
Note: this rule is not enforced for arguments to url() and other possible corner cases where developers have no control over the length of arguments.

9. Color codes

The preferred syntax for specifying colors is hexadecimal, lowercase, shortened (when possible). rgba() syntax is allowed where transparency is a requirement.

.demo {
    /* these are OK */
    color: #f00;
    background-color: #2d3436;
    box-shadow: 0 14px 14px rgba(0, 0, 0, 0.16);

    /* these are non conforming */
    color: #ff0000;
    color: red;
    background-color: rgb(45, 52, 54);
}