Sass Styleguide

sass-styleguide

# CSS/Sass Style Guide

[TOC]

## Coding Style

### Whitespace

* Indent using four spaces, no tabs. Reason: Ensures that indentation is consistent across editors, Visual Studio default.
* A space goes after the `:` in property declarations and the `{` in rule declarations. Reason: Standard pretty much everywhere.
* Leading brace follows selector, newline between last property and closing brace. Reason: Visual Studio default.
* Related selectors are grouped on the same line. Reason: Improves readability.
* There should be one empty line between closely related rules, two empty lines between loosely related rules, five empty lines between sections. Reason: Improved readability, recommended in [CSS Guidelines][6]

### Formatting

* Colors are lowercase hex `#aaa` unless `rgba()`. Reason: Smaller CSS files.
* Alphabetize property declarations. Reason: Somewhat arbitrary, improves readability.
* Zero values have no unit specification (`margin: 0` not `margin: 0px`). Reason: Smaller CSS files.
* Shorthand declarations should be limited to cases where it is necessary to explicitly set all property values. Reason: Less error-prone, prevents accidentally resetting properties.
* Avoid using IDs in CSS (they're fine in HTML and JS). Reason: IDs have too much specificity.
* Only use `!important` proactively (like in a utility class to ensure a style gets set). Reason: Reactionary use of `!important` is bad practice.

### Naming Convention

* [BEM-like naming][10] -- [More][11]
* [A relevant StackOverflow question][12]
* [Medium's take][13]
* [The SASS team's thoughts on it][14]

### Pixels vs. Ems

Some views on the subject:

> Use px for font-size, because it offers absolute control over text. Additionally, unit-less line-height is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the font-size.
> -- [GitHub's Style Guide][7]

> ...point and pixel units are not necessarily best suited for web documents, which leaves us with the em and percent units.
> -- [CSS Font-Size: em vs. px vs. pt vs. percent (Kyle Schaeffer)][8]

> It is wrong to say that one is a better choice than the other (or both wouldn't have been given their own purpose in the spec). It may even be worth noting that StackOverflow makes extensive use of px units.
> -- [StackOverflow answer][9]

### SASS-specific

* Avoiding nesting more than four levels deep with SASS. Reason: [Recommended][1] by the SASS team, improves [rendering performance][2], decreases file size, reduces unwanted specificity.
* In general, if a `@mixin` is not taking parameters, use `@extends` instead. Reason: [Recommended][3] by the SASS team, reduces code repetition in the compiled CSS.

Some articles on SASS variable naming: [Net Tuts][15] [The SASS Way][16]

### Comments

> Multiline comments are preserved in the CSS output where possible, while the single-line comments are removed.
> -- [SASS Reference Guide](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#comments)

* Is [CSS Guidlines'][4] titling method good to use?
* Should we [include TOCs][5] in our stylesheets?

* [CSS Guidelines on comments](http://cssguidelin.es/#commenting)
* [Idiomatic CSS on comments](https://github.com/necolas/idiomatic-css#3-comments)

## Folder Structure



## Resources

* [Idiomatic CSS](https://github.com/necolas/idiomatic-css)
* [GitHub's CSS/SASS Style Guide](https://github.com/styleguide/css)
* [CSS Guidelines](http://cssguidelin.es/)
* [SASS Guidelines](http://sass-guidelin.es/)
* [SMACSS](https://smacss.com/book/)
* [Enduring CSS](http://benfrain.com/enduring-css-writing-style-sheets-rapidly-changing-long-lived-projects/)

> Written with [StackEdit](https://stackedit.io/).

  [1]: http://thesassway.com/beginner/the-inception-rule
  [2]: http://code.google.com/speed/page-speed/docs/rendering.html#UseEfficientCSSSelectors
  [3]: http://thesassway.com/editorial/sass-doesnt-create-bad-code-bad-coders-do#mixins-will-bloat-your-css-by-repeating-code
  [4]: http://cssguidelin.es/#titling
  [5]: http://cssguidelin.es/#table-of-contents
  [6]: http://cssguidelin.es/#meaningful-whitespace
  [7]: https://github.com/styleguide/css
  [8]: http://kyleschaeffer.com/development/css-font-size-em-vs-px-vs-pt-vs/
  [9]: http://stackoverflow.com/a/609561/1809645
  [10]: http://cssguidelin.es/#bem-like-naming
  [11]: http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/
  [12]: http://stackoverflow.com/questions/7927193/css-class-naming-convention
  [13]: https://medium.com/@drublic/css-naming-conventions-less-rules-more-fun-12af220e949b
  [14]: http://thesassway.com/advanced/modular-css-naming-conventions
  [15]: http://webdesign.tutsplus.com/articles/quick-tip-name-your-sass-variables-modularly--webdesign-13364
  [16]: http://thesassway.com/beginner/variable-naming