CSS coding standards

Last updated December 5, 2011. Created by yhager on August 31, 2008.
Edited by sun, jhodgdon, aspilicious, geerlingguy. Log in to edit this page.

Status: Draft. Drupal core (HEAD) should adhere to the latest conventions revision.
Links: CSS coding standards issues
Drupal core "markup" component issues
~~Originating groups.drupal.org discussion~~
~~Initial proposal by Nick Lewis~~

Write valid CSS

All CSS code should be valid CSS, preferably to CSS 2.1. CSS 3.0 is acceptable too, provided the usage can be justified and the principles of graceful degradation / progressive enhancement are followed.

Concise terminology used in these standards:

selector {
  property: value;
}

Selectors

Selectors should

be on a single line
have a space after the previous selector
end in an opening brace
be closed with a closing brace on a separate line without indentation

.book-navigation .page-next {
}
.book-navigation .page-previous {
}

.book-admin-form {
}

A blank line should be placed between each group, section, or block of multiple selectors of logically related styles.

Multiple selectors

Multiple selectors should each be on a single line, with no space after each comma:

#forum td.posts,
#forum td.topics,
#forum td.replies,
#forum td.pager {

Properties

All properties should be on the following line after the opening brace. Each property should:

be on its own line
be indented with two spaces, i.e., no tabs
have a single space after the property name and before the property value
end in a semi-colon

#forum .description {
  color: #efefef;
  font-size: 0.9em;
  margin: 0.5em;
}

Alphabetizing properties

Multiple properties should be listed in alphabetical order.

NOT OK:

body {
  font-weight: normal;
  background: #000;
  font-family: helvetica, sans-serif;
  color: #FFF;
}

OK:

body {
  background: #000;
  color: #fff;
  font-family: helvetica, sans-serif;
  font-weight: normal;
}

Colors (especially hex values) are preferred to be in lowercase.

Properties with multiple values

Where properties can have multiple values, each value should be separated with a space.

  font-family: helvetica, sans-serif;

Comments

In general, all comments should follow Drupal's common Doxygen formatting conventions to stay consistent with the rest of Drupal's code base. In areas, where those common conventions cannot be applied, we resort to the CSSDoc syntax (draft).

In line with PHP coding standards, block level documentation should be used as follows, to describe a section of code below the comment.

/**
 * Documentation here.
 */

Further details on the common comment syntax may be found in the Doxygen formatting conventions.

Shorter inline comments may be added after a property, preceded with a space:

  background-position: 0.2em 0.2em; /* LTR */
  padding-left: 2em; /* LTR */

Right-To-Left

Drupal supports conditional loading of CSS files with specific override rules for right-to-left languages. For a module, the override rule should be defined in a file named <module>-rtl.css (e.g., node-rtl.css). For a theme, the override rule should be defined in a file named style-rtl.css. The rule that is overridden should be commented in the default CSS rule.

From node-rtl.css:

#node-admin-buttons {
  clear: left;
  float: right;
  margin-left: 0;
  margin-right: 0.5em;
}

Rules in node.css which will be overridden if the rtl.css file is loaded:

#node-admin-buttons {
  clear: right; /* LTR */
  float: left; /* LTR */
  margin-left: 0.5em; /* LTR */
}

As a rule of thumb, add a /* LTR */ comment in your style:

when you use the keywords, 'left' or 'right' in a property, e.g. float: left;
where you use unequal margin, padding or borders on the sides of a box, e.g.,
```
margin-left: 1em;
margin-right: 2em;
```
where you specify the direction of the language, e.g. direction: ltr;