css-coding-standard.md

CSS Coding Standards

CSS Coding Standards you must conform to when writing CSS in Xfive projects.

Table of contents

• Terminology
• Write valid CSS
• Line endings
• Encoding of CSS files
• Naming conventions
• Values
• Selectors
• Multiple selectors
• Properties
• Shorthand properties
• Order of properties
• Properties with multiple values
• Preprocessors
• Comments
• License

Terminology

Concise terminology used in these standards:

selector {
  property: value;
}

property: value makes a declaration. Selector and declarations makes a rule.

Write valid CSS

All CSS code must be valid CSS3.

When using vendor prefixed properties, you can ignore CSS validation errors it generates.

Line endings

There MUST NOT be any whitespace (spaces or tabs) at the end of lines. This means blank lines should also not contain any spaces or tabs. Inconsistent trailing whitespace can add lines to diffs/patches and makes changes harder to notice.

All text files should end with a single blank line. This makes git commits easier to read since it's clearer what is being changed when lines are added to the end of a file and it avoids the verbose \ No newline at end of file warning in patches.

Files should be formatted with Unix line endings (a newline character, denoted as \n or LF), which is also the default in Mac OS X. Do not use Windows line endings (a carriage return plus a newline, denoted as \r\n or CRLF).

Tip: configure your editor to “show invisibles”. This will allow you to eliminate end-of-line whitespace, eliminate unintended blank-line whitespace, and avoid polluting commits.

Encoding of CSS files

Encoding of CSS files should be set to UTF-8.

Naming Conventions

Use BEM class naming methodology https://csswizardry.com/2015/08/bemit-taking-the-bem-naming-convention-a-step-further/

Values

• In a declaration, the property name should be immediately followed by a colon, then a single space, and then the property’s value.
• Include a semi-colon at the end of all declarations, including the last declaration in a declaration block.
• When hex values are used for colors, use lowercase and, if possible, the shorthand syntax, e.g. #aaa. Colors may be expressed with any valid CSS value, such as hex value, color keyword, rgb() or rgba(). Note that IE8 does not support all color syntaxes and will require a fallback value.
• For property values that require quotes, use double quotes instead of single quotes, e.g. font-family: "Arial Black", Arial, sans-serif; and content: " ";.
• If a property does not require quotes (e.g. url(), do not add them. This means background-image: url(path/image.png) instead of background-image: url("path/image.png")
• Use rem units preceded by px units for a safe fallback, unless it creates an undesired effect.
• Quote attribute values in selectors, e.g. input[type="checkbox"].
• Where allowed, avoid specifying units for zero-values, e.g. use margin: 0; instead of margin: 0px;.
• Include a space after each comma in comma-separated property or function values.
• Do not use spaces around the parentheses in a function, e.g. color: rgba(0, 0, 0, 0.8);
• Use lower case function names, correct: color: rgba(0, 0, 0, 0.8); incorrect: color: RGBA(0, 0, 0, 0.8);
• Always define generic font families like sans-serif or serif.

Use unitless value for line-height if possible.

line-height: 1.25;

Do not use default values if they are not necessary to override inherited values.

Selectors

Selectors should be on a single line, with a space after the selector, followed by an opening brace. A selector should end with a closing brace on the next line. Next selector related the the previous one should be on the next line with one additional line space between them.

.nav li {
}

.nav a {
}

Avoid very complex child and descendant selectors like:

/* Wrong */
.my-inbox .flyout-content .inner .message .inbox li div.take-action .actions ul li a {
}

Multiple selectors

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

.faqs a.open,
.faqs a.close {
}

Properties

Every declaration should be on its own line below the opening brace. Each property should:

• have a single sof tab with 2 spaces before the property name and a single space before the property value.
• end in a semi-colon.

.site-name span {
  position: absolute;
  top: 0;
  left: 0;
  z-index: 10;
}

Shorthand properties

Avoid using shorthand properties when possible. Because it's easy to unintentionally override previous value.

WRONG

.selector {
  /* Set top distance. */
  margin: 20px 0 0 0;
}
.selector {
  /* Horizontal centering. */
  margin: 0 auto;
}

BETTER

.selector {
  /* Set top distance. */
  margin-top: 20px;
}
.selector {
  /* Horizontal centering. */
  margin-left: auto;
  margin-right: auto;
}

Order of properties

Order of properties alphabetically.

Properties with multiple values

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

font-family: "Lucida Grande", "Lucida Sans Unicode", Verdana, lucida, sans-serif;

Preprocessors

• Limit nesting to 1 level deep. Reassess any nesting more than 2 levels deep. This prevents overly-specific CSS selectors.
• Avoid large numbers of nested rules. Break them up when readability starts to be affected. Preference to avoid nesting that spreads over more than 20 lines.
• Always place @include statements at the top of a declaration block.

.selector-1 {
  @include clearfix();
  @include box-sizing(border-box);

  margin: 10px;
  padding: 10px;
}

Avoid @extend

Do not use @extend! It's bad for performance. Use @include (mixins) instead.

Group properties

When avoiding shorthand properties try to use adventage of preprocessor and make code easier to read by grouping properties together.

.selector {
  background: {
    image: url(path/to/image.jpg);
    position: center;
    repeat: no-repeat;
    size: cover;
  }
  margin: {
    left: auto;
    right: auto;
  }
  padding: {
    bottom: 20px;
    top: 20px;
  }
  text: {
    decoration: none;
    transform: uppercase;
  }
}

Comments

Follow the comments style used in normalize.css. The comments blocks should be maximum of 80 characters wide.

This comment style is used as the separator of the main sections. There are 2 empty lines before and after it:

/* ==========================================================================
   Section comment block
   ========================================================================== */

The following comment style is used as the separator of the subsections of the main sections. It has 2 empty lines before it and 1 empty line after it:

/* Sub-section comment block
   ========================================================================== */

This comment style is used for commenting particular page elements. It has 1 empty line before it and no empty lines after it (it is immediately followed by the rules):

/* Pager */
.pager {
  padding-bottom: 5px;
  border-bottom: 1px solid #ccc;
}

Use upper case for the first letter in comments:

/* Correct */

/* Pager */

/* Wrong */

/* pager */

License

This work is licensed under a Creative Commons Attribution 4.0 International License.