We use a modified class naming convention based on BEM and SMACSS principles. BEM refers to a Block, Element, Modifier syntax structure.

  • Reusable components (the ‘block’) are separated by one hyphen .component-name
  • Structure wrappers (the ‘element’) are content-specific layout containers dependent on a direct parent, and they cannot be used by themselves. They use two underscores in a parent__child format .component-name__left-col
  • Stylistic modifiers (the ‘modifier’) of a component are prepended by two hyphens .--featured
    • Note: In Sass, the hyphen must first be escaped like so: .\--featured
  • True/false state toggles are prepended by is-* rather than two hyphens .is-active
    • This is used when a class is going to be turned on/off by the codebehind or js, and may be changed several times within one session.
<div class="author-bio --mini --featured is-expanded"><!-- component, modifiers, js toggle -->

  <div class="author-bio__image"><!-- structure -->
    <img class="avatar" src="photo.jpg"><!-- data -->
    <span class="badge --mmc">Mastermind Community</span><!-- component, modifier -->
  </div>

  <div class="author-bio__byline"><!-- structure -->
    <h4 class="name">William Shakespeare</h4><!-- data -->
    <p class="blurb">English poet, playwright, and actor</p><!-- data -->
    <h5 class="subhead">Latest Articles</h5><!-- data -->
    <ul class="bullet-list"><!-- component -->
      <li><a href="#">The Tempest</a></li>
      <li><a href="#">Much Ado About Nothing</a></li>
    </ul>
  </div>

</div>

Please note how the classes below are nested and indented.

.badge {
  display: inline-block;
  padding: 5px 20px;
  color: #fff;
  text-align: center;

  &.\--mmc { background: $indigo url(/icon-mmc.svg) no-repeat center center; }

}

// See section on 'Whitespace' for more on this



.author-bio {
  width: 500px;
  background: $warmgray-100;

  &.\--mini { width: 300px; }

  &.\--featured {
    background: $yellow-100;
    border: 4px solid $yellow-200;
  }

  &.is-expanded {

    .author-bio__byline .subhead,
    .author-bio__byline .bullet-list { max-height: none; }

  }

}

  .author-bio__image {
    margin-bottom: 20px;

    .avatar {
      overflow: hidden;
      border-radius: 50%;
    }

    .badge {
      position: absolute;
      bottom: -10px;
    }

  }

  .author-bio__byline {

    .name {
      font-weight: 700;
      font-size: em(18);
    }

    .blurb { margin-bottom: 0; }

    .subhead {
      max-height: 0;
      font-size: em(15);
      text-transform: uppercase;
    }

    .bullet-list { max-height: 0; }

  }

Examples of Wrong Styling:

.name {
  // ...
}

.--featured,
.is-active {
  // ...
}

.author-bio {
  .author-bio__byline {
    // ...
  }
}

  1. The first example is wrong because the data class name is too common and may lead to unintended overrides. There could be also be a .student .name, which would have led to conflicting styles. Fix this by nesting the .name under a parent.

  2. The second example is wrong because modifiers are component-specific and need to be nested under a parent.

  3. The third example is wrong because the structure wrapper is already a “one time use” div. That particular selector should never appear anywhere else (unless being modified by a modifier; see the .is-expanded example above). Though it wouldn’t cause errors, the unnecessary specificity is inefficient and adds extra page weight.

Capitalization

  • All .classes should be lowercase. Words should be separated by a single hyphen -, unless separating descendents __ or modifiders --.
  • Use #camelCase for IDs.

Whitespaces

Properties

  • Use one space after the colon
  • Indent each declaration with two spaces

Rulesets

  • Rulesets are written multiline, but may be single-lined if there is only one declaration
  • Avoid nesting more than 3 deep
  • Use one empty line between closely related rulesets
  • Use two empty lines between loosely related rulesets
  • Use five empty lines between new sections

CSS Property Order

It’s easier to scan CSS when related properties are grouped together. I suggest this order based on RECESS’ guidelines:

  • Positioning
    • Position, Top, Right, Bottom, Left, Index
  • Box Model
    • Display, Flex, Floats, Width, Height, Margin, Padding, Overflows, Clear
  • Typography
    • Font, Leading, Color, Text, List
  • Visual
    • Cursor, Background, Border, Radius, Shadow, Transform
  • Motion
    • Animation, Transition