Digitpaint (S)CSS Style Guide {

A mostly reasonable approach to CSS and Sass stylesheets

High level guidelines:

• Be consistent.
• Don't rewrite existing code to follow this guide.
• Don't violate a guideline without a good reason.
• A reason is good when you can convince a teammate.

Table of Contents

1. Whitespace
2. Naming Conventions
3. Comments
4. Browsers
5. Media queries
6. Variables
7. Nesting
8. Extends
9. Includes
10. License

Whitespace

• Use soft tabs set to 2 spaces

  // bad
  .selector {
  ∙∙∙∙property: value;
  } 
  
  // bad
  .selector {
  ∙property: value;
  } 
  
  // good
  .selector {
  ∙∙property: value;
  } 

• Indent every level (nesting, selector and property)

  // bad
  .selector {
  color: red;
  }
  
  // bad
  .selector {
  .nesting {
  color: red;
  }
  }
  
  // good
  .selector {
    .nesting {
      color: red;
    }
  }

• Place a space before the leading brace

  // bad
  .selector{
  }
  
  // good
  .selector {
  }

• Only write one selector per line

  // bad
  .selector, .selector2, .selector3 {
  }
  
  // good
  .selector,
  .selector2,
  .selector3 {
  }

• Separate rules by exactly one empty line

  // bad
  .selector {
  }
  .selector  {
  }
  
  
  .selector {
  }
  
  // good
  .selector {
  }
  
  .selector {
  }
  
  .selector {
  }  

• Only one property per line with a ; directly after the property value

  // bad
  .selector {
    color: red; background: white;
    border: 1px solid red ;
  }
  
  // good
  .selector {
    color: red;
    background: white;
    border: 1px solid red;
  }

• Add exactly 1 space between the : and the property value;

  // bad
  .selector {
    color : red;
  }
  
  // bad
  .selector {
    color:red;
  }
  
  // good
  .selector {
    color: red;
  }

Naming conventions

• Use BEM as much as possible (see Harry Robbert's excellend article "MindBEMding – getting your head ’round BEM syntax" for an introduction)

  <!-- bad -->
  <div class="weather header">
    <img src="sunny.png" class="icon">
    <p class="description">Sunny!</p>
  </div>
  
  
  <!-- good -->
  <div class="weather weather--header">
    <img src="sunny.png" class="weather__icon">
    <p class="weather__description">Sunny!</p>
  </div>

• Use full names instead of abbreviations.

  // bad
  .btn {
  }
  
  // good
  .button {
  }

• Use spinal-case (.this-is-a-classname) for class names, do not use uppercase letters in class names

  // bad
  .page_header {
  }
  
  // bad
  .pageHeader {
  }
  
  // good
  .page-header {
  }
  

[⬆]

Comments

• Comment where necessary
• Write comments in proper English. Translate where necessary.

[⬆]

Browsers

• Don't do manual vendorprefixing, use a tool like autoprefixer or [prefix-free](http://leaverou.github.io/prefixfree/.

• Target features, not browsers. Prefer the use of @supports if possible, use modernizr otherwise.

• Only target IE < 9 with conditional comments.

[⬆]

Media queries

TODO

Variables

TODO

[⬆]

Nesting

• Nest based on block name

• Don't mix properties and selectors in a nesting level. Use & instead.

  // bad
  .weather {
    color: #fff;
  
    .weather__icon {
      // ...
    }
  }
  
  // good
  .weather {
    & {
      color: #fff;
    }
  
    .weather__icon {
      // ...
    }
  }

• Nest up to a maximum of 2 levels. Too many levels of nesting make especially longer blocks of code unreadable.

  // bad
  .ice-cream {
    .ice-cream__cone {
      .ice-cream__cone__wrapper {
        // ...
      }
    }
  }
  
  // good
  .ice-cream {
    .ice-cream__cone .ice-cream__cone__wrapper {
       // ...
    }
  }

• Only point down with the & selector in a nesting, never up

  // bad
  .ice-cream {
    .desert & {
    }
  }
  
  // good
  .desert {
    .ice-cream {
    }
  }
  

[⬆]

Extends

• Make abstract extends with %name instead of extending actual classes.

  // bad
  .page {
  }
  
  .page--home {
    @extend .page;
  }
  
  // good
  %centered-page {
  }
  
  .page {
    @extend %centered-page;
  }
  
  .page--home {
    @extend %centered-page;
  }

[⬆]

Includes

TODO

[⬆]

License

(The MIT License)

Copyright (c) 2014 Digitpaint

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

[⬆]

}