Bootstrap practices

This document lists down the things I've learned when working on Bootstrap projects.

Also see rscss, a Reasonable system for CSS stylesheet structure, which perfectly complements this document.

Including Bootstrap

• Use Sass: Avoid the Less version of Bootstrap. Use the officially-supported Sass version. Be aware that Bootstrap's official sources migrated from Less to Sass since version 4. #

  gem 'bootstrap-sass'            # Rails
  bower install bootstrap-sass    # elsewhere

  See: @mdo's tweet

• Avoid the CDN: Don't use the Bootstrap CDN. Any site you build to last will eventually need to grow up to extend Bootstrap. The only legitimate use of this is for quick demos and jsfiddle. #

  See: Bootstrap CDN

Components

• Graduate: Your objective is to eventually graduate from stock components into new ones. Instead of restyling stock components, consider creating new ones instead. #

  // ✗ Avoid (avoid restyling stock components)
  .jumbotron {
    background: url('....');
  }
  
  // ✓ OK
  .new-jumbotron {
    background: url('....');
  }

• Restyling stock components: Don't restyle stock components except .btn and .form-control. Everything else are too complicated to restyle (eg, navbars and tables). The stock components account for a lot of corner cases, and working around them is more effort than its worth. #

  // ✗ Avoid. You don't want to do this.
  .nav-bar {
    background: $gray;
    ...
  }

• Bootstrap's modularity: Bootstrap's modules were made to be completely separate: grids, icons, components, JS components. This means you can mix and match them: #

  • You don't need to use all the CSS components.
  • You can use different icons.
  • You can use a different grid system.

  Here are some examples of alternate systems you can use:

  • Grids: Jeet, Neat
  • Icons: Ionicons, Font Awesome

  The recommended setup is to use Bootstrap for grids, basic components, JS, and nothing else (eg, icons, stock components).

CSS

• Restyling bare elements: Avoid style bare elements like h2, h3, and so on, with anything other than fonts & margins. If you need control on the styles to display documents (like Markdown descriptions), create a prefixed component. This will prevent creeping of your own rules into components that rely on these elements to have default styling. #

  // ✗ Avoid: borders will show up everywhere!
  h2 {
    margin-top: 3em;
    border-bottom: solid 1px #ddd;
  }
  
  // ✓ Better
  .formatted-text {
    h2 {
      margin-top: 3em;
      border-bottom: solid 1px #ddd;
    }
  }

• Be selective: Try not to use everything in Bootstrap. Take _bootstrap.scss and start with the bare minimum your project will need. Comment out everything else. #

  // Core variables and mixins
  @import 'bootstrap/variables';
  @import 'bootstrap/mixins';
  
  // Reset and dependencies
  @import 'bootstrap/normalize';
  @import 'bootstrap/print';
  // @import "bootstrap/glyphicons";
  
  // Core CSS
  @import 'bootstrap/scaffolding';
  @import 'bootstrap/type';
  @import 'bootstrap/code';
  @import 'bootstrap/grid';
  @import 'bootstrap/tables';
  @import 'bootstrap/forms';
  @import 'bootstrap/buttons';
  
  // (...snip...)
  
  // Utility classes
  @import 'bootstrap/utilities';
  @import 'bootstrap/responsive-utilities';

  See: _bootstrap.scss

• Media queries: Use Bootstrap variables for media queries. This will make your breakpoints consistent with where the Bootstrap columns will break. #

  @media (min-width: $screen-md-min) {
  }

• Variable overrides: Always override the following variables. Refer to Bootstrap's variables.scss for things you can (should) reconfigure. #

  // fonts
  $font-family-sans-serif: 'Helvetica Neue', Helvetica, Arial, sans-serif !default;
  $font-size-base: 14px;
  $line-height-base: 1.42857;
  $headings-font-weight: 500;
  
  // colors
  $brand-primary: #337ab7; // your main color
  $brand-success: #5cb85c; // green
  $brand-info: #5bc0de; // blue
  $brand-warning: #f0ad4e; // yellow
  $brand-danger: #d9534f; // red
  
  $gray-light: #777777; // muted text
  $gray-lighter: #dddddd; // lines

  See: variables.scss, colors variables, typography variables

• Use Autoprefixer: Use Autoprefixer instead of Bootstrap's CSS3 mixins. Autoprefixer has been endorsed officially as of Bootstrap 3.3.

  // ✗ Avoid
  .my-component {
    @include box-shadow(0 1px 4px black);
  }
  
  // ✓ OK
  .my-component {
    box-shadow: 0 1px 4px black;
  }

  See: Autoprefixer, Less mixins

Naming

• Naming conventions: When creating new components, there's no reason to stick to Bootstrap's naming convention. Consider rscss or BEM instead. #

  // ✗ No need to follow bootstrap conventions like .panel-body (elements) or .btn-primary (modifiers)
  .eventlist { ... }
  .eventlist-expanded { ... }
  .eventlist-heading { ... }
  .eventlist-item { ... }
  
  // ✓ Better: rscss conventions are cleaner
  .event-list {
    &.-expanded { ... }
    .heading { ... }
    .item { ...}
  }

  See: rscss, BEM

• Reserved keywords: Avoid using the following classnames when making new components. They are defined as top-level classes in Bootstrap and may produce conflicts. This is a partial list of the most common ones, check the full list below. #

  alert*, breadcrumb*, close*, label*, mark, open, small, badge*

  See: list of Bootstrap keywords

Markup

• Avoid helpers: Avoid using helper classes like .pull-left or .text-right. Consider the use of these as code smell anti-patterns: anytime they appear in your code, it's a wise time to evaluate if they should be refactored into new components instead.

  <!-- ✗ Bad: too much helper classes -->
  <div class='profile-card clearfix'>
    <div class='info pull-left'>
      <h2 class='name text-center'>John Smith</h2>
      <p class='occupation text-center text-uppercase small'>The doctor</p>
    </div>
    <div class='avatar pull-right'>
      <img src='avatar.jpg' alt='Picture'>
    </div>
  </div>

  /* ✓ Better: use components */
  /* (this example uses rscss conventions.) */
  .profile-card {
    & {
      @include clearfix;
    }
    > .info {
      float: left;
    }
    > .info > .name {
      text-align: center;
    }
    > .info > .occupation {
      text-align: center;
      font-size: 0.8em;
    }
    > .avatar {
      float: right;
    }
  }

Grids

• Column mixins: Use column mixins when necessary. This will free your markup from unsemantic grid classes.

  .dashboard-layout {
    & {
      @include make-row();
    }
    > .content {
      @include make-lg-column(8);
    }
    > .sidebar {
      @include make-lg-column(3);
      @include make-lg-column-offset(1);
    }
  }

  See: Less grids reference

• Grid classes: Grid classes are okay to use in your markup. However, if they appear too often, consider making them a CSS component instead.

  Grid CSS classes include: .container, .container-fluid, .row, .col-sm-6.

  .field-row {
    & {
      @include make-row();
    }
    > .label {
      @include make-lg-column(4);
    }
    > .control {
      @include make-lg-column(8);
    }
  }

  See: Less grids reference

Icons

• Avoid Glyphicons: They're too bland of a default, so chances are you designer wouldn't wanna use them anyway. If they do, fire them.

  // @import "bootstrap/glyphicons";

• Attribute Glyphicons: If you do end up using Glyphicons, be aware that you are required to give attribution.

  Icons by <a href='http://glyphicons.com'>Glyphicons</a>.

  See: reference

Forms

• Make your own form components: The Bootstrap docs prescribe you to use .col-md-6 (and so on) to line up your forms. It's better to create your own components.

  <div class='form-field'>
    <label class='lbl'>Name:</label>
    <div class='controls'>
      <input type='text' class='form-control'>
    </div>
  </div>

  .form-field {
    & {
      @include clearfix;
    }
    > .lbl {
      width: 30%;
      float: left;
    }
    > .controls {
      width: 70%;
      float: left;
    }
  }
  /* We're using `lbl` instead of `label` because `label` is a reserved Bootstrap keyword :( */