Claws

Syntax and Formatting

• Use soft-tabs with a four space indent. Spaces are the only way to guarantee code renders the same in any person’s environment.

  .element {
      display: block;
  }

• Include one space before the opening brace of declaration blocks for legibility.

  .selector { }

• Include one space after : in property declarations.

  .selector { display: block; }

• Place closing braces of declaration blocks on a new line.

  .selector {
      display: block;
      height: auto;
  }

• Put line breaks between rulesets.

  .selector-1 {
      display: block;
      height: auto;
  }
   
  .selector-2 {
      display: inherit;
  }

• When grouping selectors, keep individual selectors to a single line.

  .selector,
  .another-selector,
  .and-another {
      display: block;
      height: auto;
  
      color: #FFFFFF;
      background-color: #000000;
  }

• Each declaration should appear on its own line for more accurate error reporting.
• End all declarations with a semicolon. The last declaration's semicolon is optional, but your code is more error prone without it.

  .selector {
      display: block;
      height: auto;
  
      color: #FFFFFF;
      background-color: #000000;
  }

• Comma-separated property values should include a space after each comma (e.g., box-shadow).

  .selector {
      box-shadow: inset 5px 5px 10px #000000, inset -5px -5px 10px #454545, inset -10px -5px 12px #334332;
  }

• Don't include spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values. This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).

  .selector {
      background-color: rgb(0, 0, 0);
      background-color: rgb(0,0,0);
  }

• Don't prefix property values or color parameters with a leading zero (e.g., .5 instead of 0.5 and -.5px instead of -0.5px).

  .selector {
      opacity: 0.5;
      opacity: .5;
  }

• Lowercase all HEX values within the same declaration. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.

  .selector {
      box-shadow: 10px #FAFAFA, -5px #ccc, 12px #DDD;
      box-shadow: 10px #fafafa, -5px #ccc, 12px #ddd;
  }

• Quote attribute values in selectors. They’re only optional in some cases, and it’s a good practice for consistency.

  input[type=text] { ... }
  input[type="text"] { ... }

• Avoid specifying units for zero values.

  .selector { margin: 0px; }
  .selector { margin: 0; }

• Use HEX color codes unless using rgba() in raw CSS (SCSS’ rgba() function is overloaded to accept hex colors as a parameter).

  // SCSS
  .selector {
      background-color: rgba(0,0,0, .5);
      background-color: rgba(#000000, .5);
  }
  
  /* CSS */
  .selector {
      background-color: rgba(0,0,0, .5);
  }

Single declarations

In instances where a rule set includes only one declaration, consider removing line breaks for readability and faster editing. Any rule set with multiple declarations should be split to separate lines.

.selector { display: block; }

The key factor here is error detection—e.g., a CSS validator stating you have a syntax error on Line 183. With a single declaration, there's no missing it. With multiple declarations, separate lines is a must for your sanity.

Declaration order

We group by type 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.

• Extends
• Positioning - position, top, right, bottom, left, z-index
• Display, flex properties, and box model
• Border and other of its properties(style, width, color)
• Background and color
• Typographic
• Other

.element {
    @extend %font-size-16;
    @extend %clearfix;

    position: absolute;
    top: 0;
    bottom: 0;
    left: 0;
    right: 0;
    z-index: 1;

    display: flex;
    flex: 1 1 auto;
    height: auto;
    @import width-full(); /* width: 100%; */

    border: 1px solid #fff;
    border-radius: 5px;

    color: #cecece;
    background-color: #000;

    font-family: sans-serif;
    font-size: 100%;
    font-style: regular;
    text-align: center;
    text-transform: uppercase;

    opacity: 1;
    transform: none;
    pointer-events: auto;
}

@todo we should have a reference to a .csscomb.json file and explain the reasoning behind it

Shorthand notation

@todo maybe use the precss postcss plugin that allows you to write things like margin: * auto; to avoid accidentally overwriting unnecessary values.

Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. Common overused shorthand properties include:

• padding
• margin
• font
• background
• border
• border-radius

.selector {
    /* margin: 0 auto; */
    margin-left: auto;
    margin-right: auto;
}