How we are using front-end toolkits

I wrote recently about how and why we are using “front-end toolkits” to document our front-end code. Creating a toolkit is our recommended approach for the majority of our front-end work. However the introduction of this process has presented several challenges not only for our front-end team but for our agency as well. I would like to share some of those challenges and how we overcame them.

Pattern portfolio? What’s that?

It was Natalie Downe who coined the phrase “pattern portfolio”.  This was the name we first adopted for our front-end toolkits. It is a great name for a set of reusable components and page examples. However as Nomensa is heavily UX focused we found that both our staff and clients found this term confusing. Many people seemed to think the term “pattern portfolio” was a collection of user experience design patterns. There was very little to associate the name “pattern portfolio” with re-usable styles for the front-end of a website. So one of the first things we did was change the name to something more understandable which clearly described its purpose.

Several names were suggested such as component library, front-end documentation and pattern library, however none of these seemed quite right. The more we talked to clients about this reusable set of styles, one name kept being used over and over again. This was ‘front-end toolkits’. We feel this name adequately describes the purpose of the reusable set of styles which consist of components and page layouts. It includes everything for the front-end of your website i.e. your website’s front-end toolkit. Our staff and clients now connect with this phrase far more positively and fully understand what we mean when we talk about it.

What exactly is a component?

Once we had adjusted the name, the next problem we faced was helping people understand the concept of a component within a toolkit. Wikipedia defines a component as “an identifiable part or element of a larger whole or system”. In the context of front-end toolkits, we can say that the ‘larger whole” or “system” is a website or a suite of websites.

In our toolkits, a component is an element or part with a specific purpose. It is designed to be reusable, but it doesn’t have to be. The best analogy of a component I can come up with is Lego. Lego bricks are designed to be assembled and connected in many ways. Each lego brick has a purpose, a specific job. Anything constructed from Lego components can be taken apart again and the pieces used to make other objects. This is the same with front-end components for a website, the components in a toolkit can be put together to form different layouts, different pages and even different websites.


How to identify a component

Once the definition of a component is understood, the next step is to identify the component for a website. Identifying a component can be quite a difficult task and it usually requires collaboration between UX, design and tech disciplines to not only identify reusable patterns but also identify variations and abnormalities in those patterns. To identify a component we usually ask a series of questions:

  1. Is this component reusable?
  2. Is this component unique to a piece of content?
  3. Are there any variations of the component e.g. typography, colour, iconography, design, functionality.

It may take quite a while to compile a list of components but once created it should contain all the main parts needed to build the front-end of a system e.g. a website. For example a basic list of components may look like this:

  • Header
  • Footer
  • Main Navigation
  • Breadcrumb
  • Main Content
  • Button
  • Pagination
  • Teaser

What is that component for?

As we started developing more toolkits for our clients, we found that simply having a list of all the components for a site wasn’t enough. In the toolkit we had a working example of the component along with documentation for the component which told the developers which HTML, CSS and JavaScript code to use and where to use it. What we didn’t have was anything to outline the purpose and expected behaviour of a particular component. This made it difficult to describe the purpose of a component not only to clients, but to other members of our development team who were likely to be integrating those components into a content management system. There was nothing to compare the component against to see if it was fulfilling its requirements.

To combat this problem, we started writing basic functional specifications for each component to outline its purpose. This not only helped with our testing and quality assurance processes, but has had the added benefit of making it easier to see where we should be creating new components rather than trying to modify existing ones.


One of the first projects we developed a toolkit for was a series of websites using the same branding. This of course is an absolutely perfect use case for a front-end toolkit. However it quickly became apparent that some websites were evolving faster than others and needed far more updates to the toolkit. Rather than trying to keep all the websites using the same version of the toolkit which wasn’t efficient or practical, we introduced versioning to the toolkits. Once a toolkit reaches a stable point in a project we release a new version of that toolkit. We use semantic versioning to convey the significance of changes between releases. Once a toolkit has been released no further work is carried out on that version. If further work is needed, it goes into the next release of the toolkit.

To make sure we keep websites using the toolkits up-to-date, as the toolkit develops we regularly upgrade each website to use the latest version of the toolkit. This prevents us from building up technical debt as we know the websites are using the most up-to-date features from the toolkit.

Recording changes

Following on from versioning, one of the most important things we have introduced into our front-end toolkits is a ‘change log’. The change log summarises every update and adjustment made to the front-end toolkit between versions. Next to each change we list out what type of change or adjustment has been made, whether it's HTML, CSS or JavaScript based. This has helped no end when it comes to integrating the toolkits into a content management system. As modifications are made to the front-end of a website and the toolkit changes and grows, it has also meant upgrading a website to use a particular toolkit version is very straightforward, as the necessary changes between versions are simply listed out in the change log.

Figure 1: An example changelog

Creating the change log is very much a manual process at the moment and does take discipline within the team to make sure it stays up to date. We purposely didn't use our Git logs to populate the change log as there may be multiple commits for one update. The change log should be a simple overview of the changes between one version of the toolkit and another.

Next steps

Our front-end toolkit process is constantly evolving as we refine how we approach our toolkits in terms of structure, performance and delivery to exceed our clients expectations. Our next steps are:

  • Looking at making our toolkits DRYer, cutting out some of the repetition we encounter between the toolkit itself and when we come to integrate it into a content management system.
  • Looking at the performance of our toolkits.  Are they as efficient as they possibly could be?
  • Integrating third party frameworks into our toolkits such as Bootstrap, Foundation, Susy and Simplicity.
  • Investigating a component API approach to integrate our toolkits seamlessly into other systems such as Drupal and Wordpress.

If you would like to share your experiences, thoughts or suggestions about front-end toolkits, please get in touch, we would love to hear from you!