Building a living style guide that details all of the colors, typographic elements, UI patterns, and components used on Made Mistakes has been at the top of my to-do list for some time.

As sole designer, developer, and writer for the site, having one probably isn’t all that crucial. Yet when iterating on the site’s design I’ve found that some of my patterns don’t always “speak the same visual language.” Having a document I can refer back to and quickly spot check for visual inconsistencies could be very helpful.

Keep it simple

With the attention style guides have gotten as of late, a nice selection of generators and tools have also matured in the open source community. Because I’m using Jekyll to publish the site, I felt it would be silly to use another tool to generate a living style guide. Even if that meant giving up the ease of setup these other tools provide by having to build out something myself.

Finding a way to do it all from within Jekyll was an important consideration since I wanted to “set it and forget it” as much as possible. Maintaining stylesheets and includes in two separate projects was a thought I didn’t really want to entertain…

So with that I bumped around GitHub and Google to see what sort of solutions existed already and found these:

Out of the bunch, Jérôme Coupé’s approach resonated with me the most since it meshed well with my current Jekyll site setup. By leveraging collections1 I could avoid littering my _posts folder with components, color palettes, and other snippets while being able to iterate over them and output individual pages if needed.

Building the style guide

To start I took a quick survey of all the Sass partials in my _assets/stylesheets2 folder to determine how I might want to organize the style guide. The biggies for me were:

Configure collections

With the structure of the style guide determined next came configuring the collections that would contain each component. Originally I planned to have a single collection named components but decided to go with a second to group together all of the color palettes used on the site.

Because I had worked with collections when I built the FAQ section of my site I had a good idea of what I was doing. To start I added the following to my _config.yml and created _colors and _components folders in the root of my project.

    output: false
    output: false

I choose not to output a file for each color/component since I planned on grouping them together on a single page. But if I later wanted to break them out into separate pages (something I did for my FAQ section I would simply change output: false to true and add permalinks to the YAML Front Matter.

Looking to the future

For version 2.0 of the style guide I may investigate taking it to the next level by constructing a complete atomic design system. Instead of collections for just components and colors I could create atoms, molecules, organisms, and templates to flush out the entire system.

I’ve seen some examples of trying to do this in Jekyll with just includes, but I think leveraging components, setting output: true on them, and getting creative with Liquid would make this a better option.

Display components and color palettes

With my two style guide collections configured I created a new layout (_layouts/style_guide.html) to strip away most of the fluff found in my article and media layouts. It’s basically a wide wrapper with just a page title and {{ content }} block.

layout: default

<div id="main" class="wrap" role="main">
  <h1>{{ page.title }}</h1>
  {{ content }}
</div><!-- /#main -->

The bulk of the content for the style guide is going to come from creating Markdown files for each component and color palette — so I started on that next. For components I went with the following YAML Front Matter followed by the bare minimum of HTML needed to create each. title and type are the only required bits with scss, module, and usage being optional to describe a component and/or link back to their source code.

title: "Main Content Default Notice"
type: notices
scss: assets/stylesheets/_notices.scss
usage: "Emphasize post text."

<div id="content" class="page-content">
  <div class="notice">
    <h4>Default Notice Headline</h4>
    <p>Donec sed tellus eget <a href="#">sapien fringilla nonummy</a>. Mauris a ante. Suspendisse quam sem, consequat at.</p>

ProTip: descriptive filenames

Be smart with your filenames if you’re trying to sort components in a logical way. The default behavior is for them to be arranged alphabetically by filename. Adding a variable to the YAML Front Matter of each component and sorting on that is one way of overriding this behavior.

Or you could hack the order sequence by doing something like this with your filenames:,,, etc.

Collection loops

After creating a handful of components, I started to refine the Liquid needed to display them. Mostly to make sure things were shaping up how I envisioned them before getting too deep into things.

My goal here was to avoid hard coding color values into each document, and instead leverage the color variables already set in /assets/stylesheets/_variables.scss to keep things DRY.

To achieve this I used a SassScript map of all the color variables found on the site along with some additional CSS to build the swatch tiles.

   Color swatches
   ========================================================================== */

.color-tile {
  @include span-columns(4);
  @include omega(3n);
  margin-bottom: $gutter;
  padding: $gutter 0;
  text-align: center;
  border-radius: $border-radius;
  border: 1px solid $border-color;
  code {
    @include font-size(16,no);
    color: $text-color;
    white-space: nowrap;
    margin: 0 2px;
    padding: 0 5px;
    border: 1px solid $code-border-color;
    background-color: $inline-code-background;
    border-radius: $code-border-radius;
    white-space: normal;

Maintaining the style guide

Updating and adding components to the style guide should be as simple as creating a new Markdown file and placing it in the _components folder. In a perfect world I would never have to touch the .md files of existing components. Cosmetic changes made to Sass files should ripple throughout the site without my intervention. Unfortunately, for those components that undergo markup changes, I’ll have repeat myself and edit two files… something that shouldn’t happen too frequently.

As always my code is available on GitHub for download and forking. The Style Guide is integrated with the rest of Made Mistakes so you may have to rip out some stuff if you end up using it.

Be sure and let me know if this has been useful. If I get enough feedback I’ll consider breaking it out into its own repository for easier forking.

  1. A feature added to Jekyll in version 2.0.0 allowing you to define new types of documents that behave like Pages or Posts, while also having their own unique properties and name-spaces. 

  2. I’m using the excellent Jekyll 3 Assets plugin for a Rails-like asset pipeline to run AutoPrefixer, minify and MD5 fingerprint CSS/JavaScript assets, and some other useful stuff.