Code standards: CSS

The status of this document is currently Draft | Work In Progress.

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

1. Preprocessor

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

• Primary files are standalone and have a filename consisting of one or multiple words (separated by underscores) followed by the extension ".scss". For example codidact.scss
• Secondary files are included into primary files and cannot exist on their own. Their filename starts with an underscore, is then followed by one or more words (separated by underscores) describing its contents and then the extension ".scss". For example _question_list.scss

Primary files must not be included into 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.

2. Naming

To see how to name CSS selectors, see this document, that 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.

Selectors (and rules in general) should preferentially 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.

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

4. Spacing

• Indent code by 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.

4a. Writing selectors

One selector is written on one line. If multiple selectors apply to one rule, each of them has one line. Each line ends with a comma, except for the last one. The last line contains the opening bracket ({) for the CSS rule. All properties are written on their own line and end with a semicolon. The closing bracket has its own line.

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

Exceptions that may be applied: If the selector is very short (one class, id or tag only) and there is only one CSS property, everything can be written on one line, with the brackets being surrounded by one space:

.green { color: blue; }

5. 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;.

Question: Should exceptions apply to border and box-shadow? So border: 2px solid red; would be allowed? I think due to the frequency of their use it might be preferably

6. 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;