factor[e] CSS Guidelines

guidelines.rdoc

1. Use the linter and don’t ignore linter warnings!¶ ↑

2. Follow standard BEM class-naming syntax ¶ ↑

csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/

.block__element--modifier

.block--modifier__element

.block__element--is-state

.block--is-state__element

<div class="media">
  <img class="media__image" src="...">
  <div class="media__info media__info--truncated">
    <h1 class="media__title">Title</h1>
    <p class="media__description--is-hidden">
      Lorem ipsum yadda yadda
    </p>
  </div>
</div>

3. Use multiple class names for modifiers vs. @extend¶ ↑

BAD:

<div class="media--alternate">
  ...
</div>

.media {
  width: 200px;
  height: 400px;
}

.media--alternate {
  @extend .media;
  color: $blue;
}

GOOD:

<div class="media media--alternate">
  ...
</div>

.media {
  width: 200px;
  height: 400px;
}

.media--alternate {
  color: $blue;
}

4. Don’t nest children more than one level deep in class names¶ ↑

BAD:

<div class="media">
  <div class="media__info">
    <h1 class="media__info__title">Title</h1>
  </div>
</div>

GOOD:

<div class="media">
  <div class="media__info">
    <h1 class="media__title">Title</h1>
  </div>
</div>

5. Avoid attributes in selectors:¶ ↑

BAD:

h1.media__title { ... }

GOOD:

.media__title { ... }

6. Avoid nesting rules. One level is okay for children of modified elements.¶ ↑

BAD:

.media {
  ...
  .media__info { 
    .media__title { ... }
  }
}

GOOD:

.media {
  ...
}

.media__info { ... }

.media__info--alternate {
  ...
  .media__title { ... }
}

7. Be very specific when targeting elements, avoid going deeper than one level.¶ ↑

BAD:

.media__image {
  img { ... }
}

NOT GREAT BUT OKAY:

.media__image {
  > img { ... }
}

8. Use one scss file per block. ¶ ↑

Don’t target elements in that file that don’t belong to that block. Give the file the same name as the block. It should be immediately obvious to any developer coming on board your project where styles for a specific block or element are defined.

<div class="media"></div>
<! -- Styles defined in: media.scss -->

9. Use grandchild-wrapping elements when positioning one block within another. Grandchild-wrapping elements should only define size and position.¶ ↑

<div class="header">
  <div class="header__media">
    <div class="media">
      <img class="media__image" src="...">
      <div class="media__info media__info--truncated">
        <h1 class="media__title">Title</h1>
        <p class="media__description">
          Lorem ipsum yadda yadda
        </p>
      </div>
    </div>
  </div>
</div>

/* header.scss */
.header { ... }

.header__media {
  width: 200px;
  float: left;
}

/* media.scss */
.media { ... }

10. Extends and silent classes¶ ↑

If you have a style that is you want to DRY out, create and extend silent classes rather than loading up a single element with a ton of modifier classes.

BAD:

.media {
  ...
}

.media--bottom-right {
  position: absolute;
  bottom: 0;
  right: 0;
}

.media--bg-blue {
  background-color: $blue;
}

.media--round {
  border-radius: 10px;
}

<!-- an absolutely positioned media -->
<div class='media media--bottom-right'>
  ...
</div>

<!-- a round media -->
<div class='media media--round'>
  ...
</div>

<!-- a bg-blue media -->
<div class='media media--bg-blue'>
  ...
</div>

<!-- a media that is round, bg-blue, and bottom right, yikes! -->
<div class='media media--bottom-right media--bg-blue media--round'>
  ...
</div>

BETTER:

.media {
  ...
}

%media--bottom-right {
  position: absolute;
  bottom: 0;
  right: 0;
}

%media--bg-blue {
  background-color: $blue;
}

%media--round {
  border-radius: 10px;
}

.media--bottom-right { @extend %media--bottom-right; }
.media--bg-blue { @extend %media--bg-blue; }
.media--round { @extend %media--round; }

.media--special {
  @extend %media--bottom-right;
  @extend %media--round;
  @extend %media--bg-blue;
}

<!-- an absolutely positioned media -->
<div class='media media--bottom-right'>
  ...
</div>

<!-- a round media -->
<div class='media media--round'>
  ...
</div>

<!-- a bg-blue media -->
<div class='media media--bg-blue'>
  ...
</div>

<!-- a media that is round, bg-blue, and bottom right -->
<div class='media media--special'>
  ...
</div>

However, if you are only extending one or two styles, just write them out.

BAD:

%media--bg-blue {
  background-color: $blue;
}

%media--round {
  border-radius: 10px;
}

.media {
  @extend %bg-blue;
}

.media--special {
  @extend %media--bg-blue;
  @extend %media--round;
}

BETTER:

.media {
  background-color: $blue;
}

.media--special {
  background-color: $blue;
  border-radius: 10px;
}

11. Be kind to your colleagues and your future self!¶ ↑

Avoid surprises, don’t write weird nested styles, don’t load up an element with five classes. Modifiers are cheap and descriptive, make new ones when you’re doing new things. Put things where you would expect to find them. Remember that you will invariably be tasked with modifying this code five years from now. Be predictable.