Rap Genius CSS Style Guide

RG_CSS_Style_Guide.scss

// css style guide

// welcome to the rap genius style guide! 
// here you will find good rules of thumb when writing css and sass. 
// of course: the only rule that really matters is:

.do-whatever { content: "it's just CSS!" }



// don't scope too much. css should read like ruby.

.cat {
  color: white; 
  .whiskers {
    border-color: blue;
    .whisker { width: 1px; } // bad!
  }
}

.cat { color: white; }
.whiskers { border-color: blue; } // good!
.whisker { width: 1px; }



// a good way to think of it is: would i scope this in normal css?

.whiskers { width: 100px; }
.whiskers .whisker { border-color: white; } // here, scoping is ACTUALLY necessary

.whiskers {
  width: 100px;
  .whisker { border-color: white; } // so let's use nesting instead
}



// single rule blocks should be compressed into one-liners:

.one-liner { display: block; }
.one-liner-again { color: blue; }



// don't do empty scopes. it adds too much clutter.

.cat {
  .whiskers {
    color: silver; //bad!
  }
}

.cat .whiskers { color: silver; } //good!



// names should be style agnostic WHEN REASONABLE!
$header-font-color: #ffc13a; //good
$blue: #5AFBFF; //fine
$text-color-when-person-hovers-but-it-is-verified: #44FF2B; //BAD! Just call it $green.



// mixins are only for code that is dynamic. if nothing is dynamic, extend a placeholder.

@mixin box {
  width: 50px;
  height: 50px; //bad!
}

%box {
  width: 50px;
  height: 50px; //good!
}



// if code IS dynamic, only include the dynamic code in the mixin

%box {
  height: 50px;
  background-color: $blue;
}

@mixin box($width: 30px) {
  @extend %box;
  width: $width; 
}



// if you have defaults, include your mixin in the extend (METAAAAAA)

@mixin box($width) {
  @extend %box;
  width: $width; 
}

%box {
  @include box(30px);
  height: 50px;
  background-color: $blue;
}



// when you call a mixin, use the variable name so that it is clear what you are doing

@include box($width: 50px);



// look: I'm not the !important police. Use it if you must. All i ask is: THINK BEFORE YOU !IMPORTANT!

.box {
  display: block !important; //bad!
  .thingy-with-inline-styles { display: inline !important; } //fiiinnnne
}



// spaces are with undescores. don't ask. that's just the way it's always been.

.my-first-div { display: block; } //bad!
.my_first_div { display: block; } //also bad! (but do it anyways)



// try to avoid unecessary binding to element types

h1.song_header { color: $blue; } //what happens if the html changes?
.song_header { color: $blue; } //better



// don't abstract yourself into a corner

.song_header { @include margins_and_padding(0 0 0 5px, 7px 9px 6px 9px); } // bad!

.song_header {
  margin: 0 0 0 5px;
  padding: 7px 9px 6px 9px;  // good!
}



// try your best to seperate structure from aesthetic 

@mixin button($color: #333) { // aesthetic information that is relevent everywhere
  @extend %simple_button;
  background: $color;
}

.song_button {  // structural information relevent to a specific page or context
  @include button;
  float: left;
}