Navigating Cancer CSS (Sass) style guide

File Structure

For starters, we're going to want to apply the boy scout rule to our CSS. A lot of our legacy code contains inline CSS and JavaScript directives like so:

-# bad
-# somefile.html.haml
- content_for :document_ready do
  $('.button').click(function(){
    alert('You clicked a button!');   
  });


- content_for :style do
  :sass
    blink
      color: red

Let's clean this up whenever we find it. Separating our CSS and JS/CoffeeScript into separate files will have the following advantages:

asset precompilation through the asset pipeline
easier to maintain
cleaner views that are dedicated to markup, not styling and interaction

Like so:

# somefile.js.coffee
# good
$ ->
  $('.button').click ->
    alert 'You clicked a button!'

// somefile.css.sass
// good
blink
  color: red

-# somefile.html.haml
-# good
-# (this space intentionally left blank)

Now, for specific style considerations:

##Selectors##

Avoid making your styles overly specific.

/* bad */
#primary div.content-box ul.list li.list-item
  color: #323232

/* good */
.content-box ul li
  color: #323232

It is okay to nest elements under an element with a class, as in the case above, but let's use this rule of thumb: If you string together more than two classes of nested elements (e.g., .content-box .list .list-item), find a way to change your markup to allow you to use fewer classes.

##Presentation and Markup##

We practice the separation of concerns in our Ruby code, and we should do so in our markup, as well. Thus, avoid markup that suggests an implementation of presentation. That is, your markup shouldn't be coupled to the presentation. After all, the whole revolution of separation presentation and markup (referencing external stylesheets) in the early 2000s began for this very reason.

Put simply, do not use classes or ids that speak to the presentation of the element. Instead, use classes that denote the function of the element. This will be critical when we eventually redesign the site. If we move away from the green and orange colors, any elements whose presentation changes will need their classes changed, as well.

-# bad
.green-box
  %p This is a green box

-# good
.informational-box
  %p This box provides some important info. It may happen to be green, but my markup doesn't need to know that.

thenickcox/nc-css-style-guide.md

File Structure