A look at how we have applied Nathan Curtis eight principles of designing systems

In 2014, inspired by the work of Lonely planet and their living style guide Rizzo, we took the first steps toward a living design system for the City of Gothenburg.

Now 3 years later, encouraged by positive results, we continue to work on our design system and component framework on a daily basis. Needless to say, we have made both good and bad choices along the way, but always tried to learn from our mistakes, re-iterate and continue to improve it.

Recently Nathan Curtis published Principles of Designing systems, where he lays down 8 principles of designing systems. I thought it might be an interesting exercise to look at these principles one by one and reflect on how we have (or haven’t) applied these in our work.


Before we begin, let me give some background information about our context and goals.

  • The City of Gothenburg has a population of around 1 million and over 50,000 employees.
  • We are currently a small team (3–4 people) maintaining and developing our design system and component framework
  • We use a template language that sits on top of our UI-framework to achieve a maintainable component library
  • A major milestone for us is to use the design system and component framework for the city’s official public website and for the city’s intranet. They are currently built on the the same technical platform and together home to about 100 different applications with separate code bases.

Ok, let’s get to it.

1: “ Systems solve the easy problems so Products can solve hard problems more easily.”

This principle embodies the reason why we decided to build our design system and component framework in the first place.

To reinvent the wheel every time we built a new application was a waste of our taxpayers’ money and left us with a myriad of solutions to maintain. Maintenance that built up over the years.

As seen in the example below, the component templates further remove complexity from our applications as they reduce a library component to it’s bare minimum, namely the content itself and settings unique to that instance.

It means less markup for a back-end developer to work with which reduces the number of errors caused by CSS classes placed on the wrong element, spelled wrong or simply forgotten.

To give an example, here’s the template markup for the library component Card.

<gbg:card color=”moss”>
<gbg:element name=”url”>#</gbg:element>
<gbg:element name=”header”>Midst In Stars</gbg:element>
<gbg:element name=”image”>
https://source.unsplash.com/category/buildings/600x400
</gbg:element>
<gbg:element name=”content”>
Won’t there. Darkness place. Without after replenis
</gbg:element>
</gbg:card>
Result: A simple card created using the Card-template. See template markup above.

2: “Include what’s shared, omit what’s not.”

Nathan Curtis argues in his post that even though a component is well crafted it doesn’t necessarily mean that it should be added to the system. The reason being that it might only solve a problem for a few or perhaps only a single application and will instead increase the complexity of both using and maintaining the design system.

We currently work close together in a small team and have up until now probably been able to avoid some of these issues and discussions. Instead we have spent a lot of time discussing the right set of components (see my previous post Creating components).

We have also applied this principle to certain page areas that often seem to be unique between websites, namely the header, footer and primary navigation. These are often tied to JavaScript behavior unique for one particular site, e.g how the navigation should look and behave on mobile. Instead of taking all these variations into account we decided to exclude these specific use cases from the library and instead see them as site specific resources.

So far, it seems like a good idea and have saved us both time (and headache).

3: “Products own their destiny, systems equip them to realize that destiny.”

From the start, we decided that the template framework should be “dumb” in the sense that it should only manipulate and transform the data sent to it.

Templates never make calls to external data sources and they know nothing about business logic.

They are built on XML, XSD and XSL, all well known and established languages. Also, XSL-transformation implementations are available in most programming languages.

When it comes to having others adopt and use the design system we have perhaps had it easier than many others. Our first milestone, as mentioned above, is to make use of the system for our public government website and intranet. Fortunately, these channels run on the same platform, have an appointed owner and development is made primarily by in-house staff or consultants.

4: “Favor community over control.”

In the future this will certainly be a critical and delicate task to handle, but given our current situation it is not something that we have had to deal with to any extent so far.

We know that the rate of development will increase as the city’s digital agenda moves forward. This means that we will have to use more and more external resources in our projects and this will probably intensify discussions around this principle.

5: “Favor elegance of simple things over flexibility of complex things.”

The template layer gives us the possibility to hide complexity in markup from our library users. Nevertheless, the aim is of course to also keep solutions in our UI framework as simple and elegant as possible.

A quote attributed to Albert Einstein comes to mind:

“ Make things as simple as possible, but not simpler.”

On a broader scale, we knew that our UI framework, and the templates in particular, would perhaps keep designers from developing applications that suit their personal taste. Therefore we need to make sure the design system offers enough flexibility so that it doesn’t compromise the usability of a product.

Our primary concern is to make sure our digital services are easy to use, efficient and accessible. Restrictions that our UI framework places on designers is motivated by reduced maintenance costs, higher quality and a more uniform web presence.

6: “Make documentation first as a tool to use, then as pictures to show, then — if needed — as words to read.”

From day one, we decided to make our style guide publicly available, showcasing our components together with usage examples and code.

Even at this point, the style guide is primarily used by the team developing the design system. Nonetheless, it has still been very valuable as it becomes clear we are developing a product in and by itself . Especially in the early days before anyone was actually using the system.

One the most used features, introduced last year, was the Try-it-yourself function that quickly let’s you copy template code from a usage example, modify it, run it through the transformation and view the end result.

In combination with the documentation about a template’s attributes and content model, it serves as a useful tool when trying out different variations of a component. It is particularly useful when we do acceptance tests.

The Try-it-yourself function of our component library. The template code is sent as an AJAX request to our REST-api which transforms the XML and return the resulting HTML.

But, for anyone visiting our current library documentation, I am the first to admit we have a lot to work on. Still we feel we are approaching the problem in the correct way, taking small steps every month.

7: “Measure success on dependency.”

The design system you are developing, and are so passionate about, doesn’t generate any value to the organisation if no one is using it. It sound obvious but I still think this principle emphasise something important.

We have, from time to time, perhaps lost focus of the overall purpose and occasionally spent time building style guide functionality and having lengthy theoretical discussions with very little practical value.

So, to measure success based on how many products use your system will probably help you stay on track, and deliver on the things you used as an argument to get started in the first place.

8: “Favor quality over quantity.”

We always strive to deliver high quality components and understand that this is critical to the success of our design system.

Could our current QA process be more rigid and structured? Definitely.

We have processes and guidelines but we need to improve and make them a natural part of the design process.

Currently:

  • We use Grunt to automate various tests to increase the quality of our code.
  • We make sure all components work with the browsers and devices enforced by the City of Gothenburg’s guidelines for web development.
  • We check that components comply with WCAG level AA (which soon by law is required of government sites)
  • We use unit tests to make sure the transformation does what it’s supposed to do, e.g. that each setting generates the correct markup.

In the future, we will e.g look into the following areas:

  • Should we complement our manual accessibility test with testing tools such as such as Tenon.
  • Can automatic visual test (on multiple platforms/browsers) for each component help us deliver higher quality code, does it match the effort of maintaining them?
  • Should we start writing unit test for our JavaScript.

The principles above was originally published by Nathan Curtis in Principles of designing systems.


This was part 8 in the publication: Our Story: Building a component library