A styleguide for Kiva - now open source

From mid-2015 through mid-2016, Kiva’s product, design and engineering teams took on a sizeable, 3-part challenge:

-- Merge the functionality and content of a separate, “beta” website – Kiva Zip – into Kiva’s main lending website

-- Make Kiva’s lending website “responsive” (i.e. easy to use across a spectrum of devices from phones to desktops)

-- Apply a major visual design and branding refresh to the site (more about that here and here)

To facilitate this process and support the evolution of our lending website in the future we decided to adopt the idea of a “living styleguide” and create one for Kiva. The goal was to create a repository of design building blocks that help increase consistency across the site and speed future additions. This post is a short look at what we did and what we’ve learned, and an announcement that the result of our work is now open source at https://github.com/kiva/styleguide.

“A style guide (pattern library) is almost the de facto deliverable of any responsive redesign.”

-- Ethan Marcotte

After reviewing possible tools and processes for creating a styleguide, we settled upon Pattern Lab, by Brad Frost and Dave Olsen, and chose to be guided by Brad Frost’s principles of “atomic design” which Pattern Lab is built around. We also decided to build our new design upon the Foundation framework from Zurb.

You can view Kiva’s resulting styleguide at http://styleguide.kiva.org. And you can now see, download, fork and offer improvements to its code here on GitHub.

Going beyond design and prototyping

Pattern Lab is primarily a tool for prototyping and design. But as the Kiva team built up a library of elements in our styleguide, many engineers resisted the idea of simply copying example code from the styleguide into our website’s codebase, then editing and modifying it there for a specific use case. They argued that components were already well-realized in the styleguide code, and contended that recreating these in the website code would be additional work. Moreover, it would create a risk of divergence from the canonical versions in the styleguide.

So a couple of enterprising Kiva engineers, Noah Balmer and Joshua Kiwiet-Pantaleoni, built a system that exports CSS, Mustache templates, and style-related Javascript from our styleguide repository, then allows it to be imported as a dependency into our website codebase. We think this pushes Pattern Lab beyond its typical usage pattern

Using Grunt as a build tool, we added an export function in the styleguide’s Gruntfile.js that creates an “export” directory alongside Pattern Lab’s other top level directories. When called inside the Grunt “release” function the export function copies a subset of pattern, CSS, and javascript files from Pattern Lab’s public directory into the export directory. The release is then pushed to GitHub. Over in the lending website’s code, we add the styleguide as a dependency in its package.json file...

 "styleguide": "git+ssh://git@github.com:kiva/styleguide"

This causes npm to import the styleguide’s exported files. Symlinks elsewhere in the lending website’s code point to the _pattern directory and other imported files from styleguide where npm has placed them them within the node_modules directory.

Also, since developing for the lending website now involved work in 2 interrelated but separate git repositories, we built a shell script to help developers keep local development environments of both repositories in sync. And, since paths and filenames in the styleguide were embedded in code on the lending website, creating a barrier to renaming or reorganizing styleguide files, engineer Zvi Boshernitzan created a tool in PHP to assist with adjusting included pattern file paths in both repositories simultaneously upon file moves and renames. (This tool is currently not in a public repository.)

Practices we’ve followed

We made a decision that “atom”-level elements would not be incorporated into more-complex elements via Mustache includes, but rather that we would copy-paste them into higher-level constructions as needed. This helped avoid proliferation of atom-level elements as customized for each application.


Also, we decided that the highest complexity level in the Pattern Lab hierarchy – “pages” – would be used only for design review of composed pages by stakeholders. So, typically, we compose all elements within a given page’s chrome at the “template” level. The resulting template can then be used as a Mustache include for a given page in the lending website. The “pages” version of the same content then will surround the template content with the site’s header, footer and navigation elements, allowing stakeholders to review a fully-composed page as visitors will see it.

An additional complexity is that – for certain pages that are largely or completely static content – (pages like terms-of-service, marketing landing pages, volunteer recruitment pages and the like) we compose those pages in styleguide, but then copy-paste the rendered HTML of the composed templates into our Drupal-based content management system. In these cases, the version in the styleguide is no longer “living” once migrated to the CMS, because non-engineers are free to modify the content as desired within the CMS. For these pages, their continued presence in the styleguide is only to serve as a jumping-off point if a future significant redesign of the page is to be done.

Things we’ve learned

There are trade-offs involved in our decision to make our styleguide play the additional role of a kind of repository for production code.

For example, consider the case of a simple molecule with an icon on top of 2 or 3 lines of text, like this – a pattern we use in many places on our site:



If we used the cut-and-paste model, we’d just need this one molecule in the styleguide, which we’d insert with some placeholder JSON for the content in any organisms where we use it.

But, because we want the final content for each instance of this pattern to be in the styleguide, we have multiple instances of the pattern each with its own icon and text.

The result is a significantly larger styleguide than if we had used it solely as a design and prototyping tool. And there is extra overhead in the development flow created by the steps of making a set of styleguide changes available to the lending website by doing a Github release of the styleguide, then updating the dependency in the lending website’s code.