Boilerplate

When work at an agency, you set up new sites all the time. If you work at an agency that does fully custom sites, coming up with a sensible and globally-useful boilerplate is challenging. You don’t want it to be blank and have to totally re-create the wheel every time, but you also don’t want to be spending a bunch of time stripping out unused styles (or worse, leaving them in). Boilerplate is not a set-it-and-forget-it type of thing. I tweak it nearly every time I start a project (tweak being the important word there, if I made major changes every time it wouldn’t exactly be “boilerplate” would it?).

Boilerplate consists of a lot of bits and pieces: dependencies (any plugins you always use, a CMS, modules, etc), starter template files (aka HTML), style sheets, build files, etc. Obviously it will depend on what kind of framework or CMS you’ve got running. To be overly specific, a few things mine consists of

  1. gulpfile.js
  2. package.json
  3. FUEL CMS
  4. humans.txt (okay I haven’t updated this in a long time, I’m pretty sure it lists people who don’t even work here anymore, and is mostly a huge ascii drawing of our logo anyway)
  5. Starter view files (header, footer, etc)
  6. gitignore
  7. CSS starter (mixins, boilerplate)
  8. a styleguide boilerplate program

For me, the challenge really lies in writing boilerplate SASS and HTML that has a nice jumping off platform. I tend to lean on the side of not enough, rather then too much. I also have a digital notebook of code snippets I can paste in when needed. Most of that is PHP since I’m not an expert there, and other things I hate doing like Social Sharing links.

Screen Shot 2015-03-13 at 9.16.05 AM

 

HTML Boilerplate

The problem with telling you all about my awesome boilerplate, is that much of it is going to be CMS-specific. Thankfully, FUEL allows you to write all your own HTML, it ain’t no Drupal. A few lines of code I find especially useful:

<link rel="apple-touch-icon-precomposed" href="<?=site_url('apple-touch-icon.png')?>">
<?php // also include apple-touch-icon.png at root, 152x152 ?>

Write notes for yourself! I put comments in everywhere, especially for things like touch icons, where I find myself having to Google the size every.damn.time. Just make sure your comments are in a compiled language, so they don’t show up in the HTML.

By default, I also include Respond.js and HTML5shiv for IE8. I’ve also taken to including SVGeezy as well, for PNG fallbacks for SVGs.

CSS & SASS

You may be surprised how barren my main.scss file actually is. I inherited this boilerplate from my predecessor, who based it off of HTML5 Boilerplate and the semantic grids system. A few of my favorite lines:

*, *:before, *:after {
  -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box;
 }

I can’t even imagine not using border-box.

%first_last_margins {
    &:first-child { margin-top: 0 }
}

So that the first item in a container, like paragraphs, lists, and headers won’t have a top margin. Quite handy, although overriding it is a huge PITA. I haven’t found a better solution, and I rarely find myself having to.

@for $i from 1 through 12 {
    %column#{$i} { 
        @media (min-width: $smWidth){
              @include column($i);
              padding-bottom: 0;
        }
    }
}
%narrow-column {
    @media (min-width: $smWidth){
        @include column_center(10);
    }
}

I have a _grid.scss partial that contains the actual mixins, but I use the above to create placeholder classes for use in the selectors. Something to note: yes, I put a media query in there! I find that most of the time, columns collapse for mobile. I can very simply just not use this placeholder and instead directly use the mixin when necessary, but using extends allows me to use a semantic grid system without repeating the same 5 lines of CSS over and over again all over the stylesheet.

The ever handy narrow column placeholder is for those centered narrower columns that our designer seems to always want to use. The column_center mixin is pretty straightforward:

@mixin column_center($x,$columns:$columns) { 
    width: ($total-width*(((($gutter-width+$column-width)*$x)-$gutter-width) / $gridsystem-width));
    margin-left: auto;
    margin-right: auto;
}

Rather then including column(10) and then overriding the margins, it makes more sense to me to use the width equation directly, since that’s all I really want anyway. I suppose I could abstract that out from both mixins, but I rarely touch this code.

Also included: print styles, some CMS-specific classes (which are empty, but the selectors are there as reminders), helpers (which includes things like clearfix and some alignment classes), and some baseline styles for headings, lists, and so on. Of course the whole thing starts with a CSS reset, but that goes without saying, right?

Much of my boilerplate is actually a series reminders and notes, and convenience functions. Every time you find yourself having to open up an old project to see how you did something, consider adding it to your boilerplate. The beauty of SASS is that you can add all the placeholders and mixins you want to your partials without fear of bloating up your CSS. HOWEVER, like all things code, you must maintain it. You should review every line on a continuous basis so you can get rid of things as you no longer need them (which reminds me, probably don’t need those icon font helpers anymore…). Otherwise your boilerplate will get so large you’ll forget what’s in there and it will cease to be useful.

As I mentioned above, I’ve been using a Styleguide generator in my start files, and I’ll go through the ends of outs of that on my next post. It reads in variables from my SASS partials and auto-magically dumps them in. Stay tuned!