The website as an instantiation of your design system

In his talk at Beyond Tellerand last year, web designer Brad Frost talked about the website “as an instantiation of your design system”. I really liked that idea.

Design can be defined by many things: it is a thought process, the result of abstract thinking, something that requires research and a sense of style. From a practical point of view, it can be described in terms of the materials it is made of. Paint, wood, glass, ink… This is slightly different for web design. Web design, in particular, is made of some very specific materials: HTML, CSS, JavaScript, typefaces and images.

Design on the web, more than any other type of design, can be documented in a way that is powered by the materials it is made of. Pattern libraries can do this.

Pattern libraries

A pattern library is a set of components, in which each component can include:

  • Documentation
  • Mark-up in HTML (or Twig or Haml or Mustache)
  • Style in CSS (or Sass or Less or Styles)
  • Scripts in JavaScript (or Coffee Script)
  • Images

Each component has at least documentation and mark-up.

The set of components, as a whole, describes the design system that exists in your website. The components, plus perhaps a couple of files like typefaces, a logo and an icon set (although they could be components of their own).


The advantages of separating your design system out as front-end components are plentiful:

  • great reference for all people involved in the project
  • potentially a better workflow, as there is only one place where common patterns are created
  • easier to spot and avoid inconsistencies in both design and code (‘Oh wait, we’ve already got a datepicker!’, ‘Actually, we can reuse most of that existing markup for this new button style’)
  • more testable as everything is abstracted and nicely separated and organised, this makes it easier for a script (or anyone) to test

Zombie style guides

To create a style guide as an overview of your website’s design system and the corresponding code is one thing. To maintain it, is another. In her Fronteers 2015 talk, Anna Debenham referred to a phenomenon known as zombie style guides, style guides that live separate from the web project they power, and are not actively maintained. They are no longer as useful as they were at the start of the project.

To avoid that, a style guide should be what powers your actual website(s), so that your website(s) become instance(s) of your design system.

The website as an instantiation of your design system

This is what Brad Frost suggested in this talk at Beyond Tellerand in Düsseldorf (Video, scroll to 39:00):

“The website is one instantiation of your design system”

I think this brilliant. In the ideal set up, there is a set of components, and then those components are used in places. The set is built, updated, improved, refactored etc separately from the places it is used in. The website, but also a front-end style guide are just examples of places.

Brad quotes Nathan Curtis:

“A style guide is an artifact of design process. A design system is a living, funded product with a roadmap & backlog, serving an ecosystem.”

Copy/pasting mark-up vs “real” instantiation

One way a website could be an instantiation of a design system, is if all markup in the site is copied from the style guide. The copy/paste method is easiest to set up.

A much better and more ideal way, is if the site uses code to grab a copy of the actual markup for a component. This markup could live in its own repository so that it can be modified, refactored and improved. For example:

includeMyComponent('button', { text: "Click here" })

could render as this today:

<span class="button">Click here</span>

and render as this tomorrow, after an update to the component library:

<button class="button">Click here</button>

New mark-up, same include function.

The holy grail, Frost concludes, is a “magical setup” that contains “all the lego bricks of a site”, and if we make a change, anywhere that lego brick is updated, it just magically updates. Like the example above. Ian Feather and his team at Lonely Planet have built a system that can do this, with their API for components.

The front-end style guide

The front-end style guide, like the website, can also be seen as an instantiation of the design system. It is just another place that consumes your organisation’s set of components.


There is one important difference though: a front-end style guide should, in my opinion, serve as documentation. So not only should it consume the components themselves, it should consume components with their documentation.

The person who builds a component, will have to write its documentation. This is essential, as a few month’s later, they may have left the team. Or they may still be on it, but have forgotten about what the component was for.

Documentation of a component should explain what it is, what it is used for and what its options/parameters are.


To summarise my thoughts: I think web design is a special type of design as it can be documented with the same materials it is made of: markup, stylesheets, scripts et cetera. This can be done by structuring the design in the form of a system of components. This system can then power both the website and a showcase of documented components. Statically, or, ultimately, dynamically.

For more info on different types of style guides and approaches to building ones that ‘live’, I can recommend watching Anna’s talk at Fronteers and Brad’s talk at Beyond Tellerand:

Comments, likes & shares

No webmentions about this post yet! (Or I've broken my implementation)