(Living) Styleguide Driven Development

When building Blackwell’s new eBook platform, I wanted to implement a living styleguide to make the CSS maintainable over the project’s lifetime.

Check it out here. You can navigate through the patterns using the navigation on the left.

Blackwell's Pattern Lab

As an aside, something that you might not be familiar with is the idea of dividing your CSS into Atoms/Molecules/Organisms. This is a great idea taken from the excellent patterlab.io site.

Pattern Lab IO

The CSS is built using the SuitCSS methodology which I’m a big fan of.

Back to living styleguides… 🙂

Primarily thanks to Twitter Bootstrap, people have become familiar with modular CSS which can be reused. Combined with the popularity of “OOP” style CSS approaches like SMACSS and BEM, CSS seems to have come of age and there are methods and tools in place to avoid the CSS spaghetti of the past.

A living styleguide takes that concept a step further. What we’re trying to achieve is:

  1. Avoiding duplication (of HTML) to reduce maintenance costs and regression bugs
  2. Ensuring CSS and template logic is easily repeatedly testable to prevent regression bugs

A lot of people are building sites and applications with styleguides, but where they often stop short is that once the styleguide is created they duplicate the HTML used in the styleguide into the actual “live” project.

So, the rules of living styleguide development are quite simple:

  1. Your site should be built from modules (the styleguide) which form your pages/views.
  2. Each module should have it’s own template/partial which can be passed test (fixture) data or real (live) data.
  3. When you create the module, create all variations the template allows using test (fixture) data.
  4. When you edit your CSS or templates, check the tests to ensure you haven’t broken any of the variations or layout.

If you’re familiar with test driven development you’ll be familiar with the approach, although since this is CSS the testing is manual not automated. Note – you could automate Selenium tests on these too, but I’m focusing on visual testing here – i.e. how layouts, spacing, fonts, alignment appear.

Living styleguide driven development has another aspect which is that it becomes much easier for designers to review all the variations of the frontend templates. This avoids situations where designers need to visit multiple pages on a site to see all the variations – instead they can go to the living styleguide and view them in one place.

Another benefit is that you can test edge cases. Often when building data driven sites a number of bugs appear once user generated content is passed into templates. Testing your templates with large amounts of text before integrating with a CMS catches those issues early.

Envato have a great post on living styleguides which goes into more depth, it’s well worth a read.