CSS Style Guide


This page outlines the style guide for CSS across all jQuery projects.

link Linting

Use CSSLint to detect errors and potential problems. Most jQuery projects have a Grunt task for linting all CSS files: grunt csslint. The options for CSSLint are stored in a .csslintrc file.

Each .csslintrc file follows a specific format. All options must be alphabetized and grouped:

1
2
3
4
5
6
7
{
"common1": true,
"common2": true,
"repo-specific1": true,
"repo-specific2": true
}

The following common options must be used in all projects with css:

1
2
3
4
5
6
7
8
9
10
11
12
{
"adjoining-classes": false,
"box-model": false,
"box-sizing": false,
"compatible-vendor-prefixes": false,
"duplicate-background-images": false,
"import": false,
"important": true,
"outline-none": false,
"overqualified-elements": false,
"text-indent": false
}

link Spacing

In general, the jQuery style guide encourages liberal spacing for improved human readability. The minification process creates a file that is optimized for browsers to read and process.

  • Indentation with tabs.
  • No whitespace at the end of line or on blank lines.
  • Use a space after a property name's colon, do not use a space before the colon.
  • Put a space before { in rule declaration.
  • Place the closing brace of a rule declaration on a new line.
  • Put a blank line between rule declarations to make the CSS readable.
  • When listing multiple selectors associated with the same CSS rule, add a new line after each ,.
  • The only time you should indent selectors is within nested rule declarations, like media queries.
  • CSS rules' properties should be indented by one tab.
  • No spaces within () for urls.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/* Bad CSS */
.bad-spacing,.bad-example{color:#222222;background:url( "../bad.png" );}
.bad-spacing{font-style:italic}
@media only all{
.media-example{
font-weight:strong;
}
}
/* Good CSS */
.good-spacing,
.good-example {
color: #222;
background: url("../good.png");
}
.good-spacing {
font-style: italic;
}
@media only all {
.media-example {
font-weight: strong;
}
}

link Formatting

  • Use hex color codes (#5c8fb3) unless using rgba().
  • When possible, use shorthand hex values.
  • Use lower case letters when declaring hex codes.
  • Use em over px, unless unavoidable.
  • Don't specify units for 0 values.
  • Avoid cascading selectors that are more than 3 selectors long.
  • Avoid unnecessary cascading selectors.
  • Use shorthand properties when possible.
    • Instead of writing out padding-left: 10px; padding-right: 10px; padding-top: 20px; padding-bottom: 5px;, shorten it to one rule: padding: 20px 10px 5px 10px;. However, if you're only changing the left padding, then it is appropriate to use padding-left.
  • Omit leading zeros in decimal values.
  • Use double quotes instead of single quotes.
  • Always have a semicolon at the end of each declaration.
  • Avoid the use of !important.
1
2
3
4
5
6
7
8
9
10
11
/* Good CSS Example*/
.good-table thead th {
color: #fff;
background: #ffc0cb url("../images/polka-dots.png");
font-size: 1em;
padding: .5em 0;
}
.good-table thead th.selected {
padding-left: 1em;
}

link Imports

  • Don't use @import in distribution files. It is slower, adds extra page requests, and can cause other unforeseen problems.
  • Do not use more than 31 @imports in a single CSS file, it will break IE.
  • Do not nest @imports, you will not be able to guarantee their order.

link Comments

Comments are always preceded by a blank line. Comments start with a capital first letter, but don't require a period at the end, unless you're writing full sentences. There must be a single space between the comment token and the comment text.

When comments take up multiple lines, use a * at the beginning of each line. There must be a space between the first word and the * on each line.

1
2
3
4
5
6
/* Good single line comment */
/*
* Good example of a multi-line comment.
* If your comment takes up multiple lines, please do this.
*/

link Class Names

  • Class names should be all lowercase letters.
  • Build class names with hyphens (-).
  • Avoid excessive and arbitrary shorthand notation for classes. .ui-button is useful for button, but .b doesn't mean anything.
  • Use classes to identify selectors instead of ids.
1
2
3
4
5
6
7
8
9
10
11
12
/* Bad Example */
.uiButton,
.ui_button,
#uiButton,
.b {
}
/* Good Example */
.ui-button {
}