CSS & Sass

As our team grows we want to evolve our CSS practices so they’re scalable, enable rapid development, and are sane to debug.

Here’s a great read about html semantics and using them to help developers.

Guiding principles of the choices in this document are to:

  • Reduce selector nesting in Sass files.
  • Improve at a glance clarity of our markup. You should be able to visualize what something looks like onscreen from looking at the associated HAML.
  • Reduce the number of JavaScript bugs that arise from changing presentation related elements.

It’s an adaptation of BEM. BEM stands for “Block, Element, Modifier”. Blocks are modules or widgets. Elements are subelements that belong to that widget. Modifiers are visual variations on that widget. This is what our syntax variation looks like.

Naming convention

  • Blocks: Named in lower case, using - to separate words
  • Elements: Named with “_module-name” using _ to denote being a subelement
  • Modifiers: Named with “–mod” using “–” to denote being a modifier

Never create nested elements inside one another. Block/element structure should be flattened while the DOM structure can be nested as needed.

For example:

.block {}
.block__elem1 {}
.block__elem2 {}
.block__elem3 {}


<div class="block">
  <div class="block__elem1">
    <div class="block__elem2">
      <div class="block__elem3"></div>


This includes things like font size variations, alternate color schemes, width variations, inlining of elements that are typically block elements (think forms).

# hamlc template
.sidebar.sidebar--align-left # <- left align modifier
# Scss
.sidebar {
  width: 300px;

  %position {
    position: absolute;
    top: 0;

  &--align-right {
    @extend %position;
    right: 0;

  &--align-left {
    @extend %position;
    left: 0;