Formatting CSS

Published: The following article represents my preferences regarding formatting CSS (in a large web applications).

Motivation beyond formatting CSS

Style matters. Readability, how quickly you can scan through selectors and their properties also matter. A lot. Having a clear structure is important. Naming convention is tough. All this is often underestimated. Develop your own set of rules and stick to them, document then if necessary, which is usually when teams get bigger. Below is what works for us.

General rules:

  • Use lowercase (both for properties and selectors) and dashes-to-separate-words,
  • Avoid styling IDs,
  • For single line rulesets, put space after the colon ,
  • For multi line rulesets, also put space before the colon  : ,
  • Four spaces before each declaration (no tabs),
  • Opening bracket on the same line as the rule set, preceded by one space  {,
  • Closing bracket appears on its own line after the final property },
  • Properties are grouped by type,
  • Align property values,
    This is rather unique and seldom used, but I argue it improves readability. It feels rather odd until you get used to it, but after that it is pleasing to the eye.
  • Ensure empty line between each ruleset except unless… read below on Single or multiple lines?.

Shorthand properties?

Use the long form for colour declaration. Try to stick to lowercase 6 digit hex format wherever possible (unless using rgba). Not all can be expressed as a three hex digit, therefore to avoid diversity, we use longer form. It makes it easier to search for certain colour across codebase.

With other properties where shorthand is also an option, we do not have strict rules, but just keep in mind that you can override previously set propertiy when declaring shorthand properties while you leave some properties out.

Example:

p { line-height: 16px; }
p { font: 12px Arial; }
Guess what's the line-height of a p element? No. It's normal.
Therefore whenever you use shorthand property, better declare all of them.

Single or multiple lines?

Both, actually. If a rule contains only one property, we use single line approach:

Example:

.notice-warning { color: #ff0000; }

Usually when specifying only one property it means we are dealing with rather small changes, such as colours, widths of table cells, icon images or their background positions when using sprites, or the likes. In that case we use single line. Selectors as such are usually grouped and declared in a consecutive order (with no empty lines in-between), which allows for quick scanning of their names along the left.

Examples:

.icon-mute { … }
.icon-play { … }
.icon-pause { … }

In case of unrelated rulesets with only one property, we put an empty line in between them.

If a rule contains multiple properties, we use multiple lines and we always keep an empty line in between rule sets.

Example:

.modal-box {
    width              : 40%;
    height             : 200px;
    overflow           : hidden;
    background-color   : #dddddd;
    -webkit-box-shadow : 10px 10px 5px #888;
    -moz-box-shadow    : 10px 10px 5px #888;
    box-shadow         : 10px 10px 5px #888;
}

Until the myriad of vendor-specific prefixes saga I used to keep selectors as one-liners, but after that things tend to get out of hand way too easily. Also, when performing diff comparison (version control, such as Git), keeping each property and value on its own line is a big advantage.

Grouping Properties

Chris Coyer posted a poll questioning how do you order your CSS properties which yielded following results:

Randomly:
39 %
Grouped by type:
45 %
By line length:
2 %
Alphabetical:
14 %

We tend to use combination of above. We group by type and within that scope we toggle between arbitrary order and order by line length. Types are ordered by their importance, from loose to more specific properties:

  1. Positioning
    position, top, right, left, bottom, z-index
  2. Display and box properties
    display, box-sizing, width, height, padding, margin, overflow
  3. Border
    border and its properties (style, width, colour), border-radius and seldom, border-image
  4. Background & Color
    background, color
  5. Text declarations
    font-family, font-size, line-height, text-align, text-transform, letter-spacing, etc. Anything that affects the display of the type
  6. Other
    cursor, pointer-events, etc. anything else that does not fit into above categories

Final example, with comments, to sum up the rules above

button {
    position       : relative;          /* Positioning */
    z-index        : 6;                 
    display        : inline-block;      /* Display and box properties */
    width          : 90px;
    height         : 24px;
    margin         : 0;
    padding        : 0;
    border         : 1px solid #999999; /* Border */
    border-radius  : 2px;
    background     : #333333;           /* Background & Color */
    color          : #ffffff;
    text-align     : center;            /* Text declarations */
    text-transform : uppercase;
    font-family    : Arial, Helvetica, sans-serif;
    line-height    : 12px;
    font-size      : 12px;
    cursor         : pointer;           /* Other */
}
                                        /* Empty line after multi-lines rulesets */       
button.narrower { width: 80px; }        /* One property, one liner */
button.wider    { width: 120px; }       /* No empty-line in between related rulesets */
button.widest   { width: 170px; }
            

Consistency is the key

Whatever you choose your style to be, at the end of the day, the most important part is consistency. I encourage teams to establish their own set of rules and be consistent with it. Choose what feels natural and makes sense to you. Whether you think it needs to be documented or not, it is up to you and the size of your team.

Some say if a document is well-styled, it is self-documented, but when teams get bigger, it is hard to ensure consistency across codebase.

This article only covers how to format CSS rules. It does not cover:

If you have further interest, you might want check out the list of style guides for CSS from the expers such as GitHub, Google, Smashing Magazin and others. The list contains plenty of good takeaways, noted in quotes from each style guide.

blog comments powered by Disqus