Building a Design System – The challenges we face

Building a Design System – The challenges we face

At Moxio we develop a suite of applications. These applications can work together or stand alone. Keeping the UI and interaction consistent between functions, views and different applications is quite a challenge. To make it easier to develop new views and functions and to offer our users a consistent UI and interaction we started building a Design System. In this blog, I will tell about the challenges we are facing while developing this system and what the gains are up until now.

What is a Design System?

If you’re building digital products you’ve probably already heard about Design Systems, so I won’t dive too deep into that. In short, what is a Design System; A Design System is a tool to build consistent digital products. The coverage of your ‘system’ depends on how integrated and comprehensive you make it. Design Systems could range from digital style-guides with typography and color hashes to UI and interaction patterns and corresponding PHP widgets.
For examples of different Design Systems take a look at It depends on the project or kind of product how comprehensive and integrated your Design System should be.

Why we are building a Design System

When I started working at Moxio there wasn’t much style documentation. Mainly I used existing views and functions to trace, copy and paste from to create new views or functions. A lot of my time was consumed by finding similar elements and designing elements that in the end already existed but couldn’t be found because of lack of overview.

Inconsistency was hurting my eyes and knowing I was also contributing to it made me realize this needed to change. Fast!

We needed a system, so that we could design and develop consistent UI’s and interaction patterns. So we could spend our time on improving and innovating instead of inventing the wheel over and over again. Beside that give our users a seamless experience while working with either which of our applications.

Researching our options

I started researching what our options where. I already knew a collection of elements (color, typography and basic elements) as a classic style guide wasn’t going to work. Over the previous months I collected most of those and documented them. But these files were only available to me, there was no communication about them, it only effected the new designs I’ve made and had no impact on everything that was already used in the applications.

For example, from the five color shades of black I found in the application used for body text I selected one to use in my designs. But the chosen color only got implemented in new views or functions and so legacy was kept alive and months later you could still find five different shades of black in the application. And this was just an ‘easy' element.

Easy element color

Inventory of the 'easy' element color, I found in two views

To get consistency in our applications on different levels we needed something which many disciplines could work with instead of just designers and maybe some front-enders. So we needed a system that could cover design, interaction, code and usage that would be integrated in a way it also gave us the opportunity to clean out legacy.

Methods and examples

I’ve looked at atomic design, a method for approaching and structuring elements in your design system and Ge’s blog about their design system in which they build up on atomic design. Material design what I think is a way to approaching design and design principles for a brand rather than a method.
Also Salesforce Lightning Design System and Futurelearn Pattern Library
are examples of design systems in which I see our system develop. They contain documentation
and examples about style, code and implementation.

Inventorying elements

Inventorying elements

Challenges we are facing

So I knew what I needed, I had an idea what other disciplines at Moxio probably needed and I had a few ideas about how to structure everything by the methods and examples I found. But there were a few challenges we faced starting and working on the Design System.

Getting everyone on board

At start

A Design System is not a one-man project and if you want it to succeed you need everyone on board. The more integrated you want it the more disciplines you need at the table. We are building a suite of connected applications, which means they share a lot. Design and code is already integrated through different applications. For me it meant I wanted everyone on board so I could pitch my idea and get their input to improve.

I confronted the team with the inconsistencies I saw to explain the problem, got in different methods we could use and asked them what should be in the system from their point of view to determine how integrated it needed to be. This way we could get everyone involved by understanding the problem and got an overview what different disciplines’ needs and wishes for the system were. From the front-end/development team there was also a need for more code integration and examples (when and how to use). The front-end could also use the design system project to refactor and implement a new CSS pre-processor while we are picking up elements for the design system.

During the process

We’ve involved everyone at the beginning but during further development not everyone was working on the Design System project (yes, we have other things to do, see the planning and priority challenge). Sharing the process of the Design System, which elements were new, keeping people who are not actively involved in the project connected and keep them in the loop about decision making was a challenge. We had a bumpy road right there with some heated discussions and confusion.

Communication was the main problem. We needed to communicate our planning better, which elements were done or updated, which old elements shouldn’t be used anymore, etc. Also we started giving demo’s to the whole team about new elements and how they work and should be used. This way people were up to date and also could hitch on when needed.

Planning and priority

We are not Salesforce or the UK government. Compared to them we are a relatively small team and while working on the Design System we need to continue working on our suite of applications, bug fixing, developing features, views and new applications. The Design System is just another project besides this. Therefore, we have to plan and prioritize the elements so we can work on the Design System and other projects at the same time, this doesn't mean our solution shouldn’t also work for larger teams.

For this we divided the patterns in two types

  • Elements that aren’t needed direct and can be picked up when we come across them. For example when we are developing a new feature or redesigning an existing one.
  • Elements that are used everywhere like color, buttons, icons etc. which we come across all the time and need detailed planning not to get in the way with production.

With this category of elements, we can plan the development of elements in the Design System in a flexible way around production. In some cases, the development is triggered from inside the Design System project but it can also be triggered from product development.

Design System board on Trello

Design System board on Trello

Production vs. Design System

Design styles and code are integrated deep in to our applications. To make sure the Design System isn’t affecting the application in a way style or functionalities break or users get confronted with incomplete style changes. We need to plan the development of an element so it doesn’t break our applications.

To make sure this doesn’t go wrong, these are the steps we take when taking up elements for the Design System.

  1. Make a template with an inventory of the element
    We make an inventory of the element by showing the element in all the contexts and states available in one template. This way we can estimate the impact of the changes we want to make and prevent that we’re missing a state or context it’s used in.
  2. Decide what needs to be done to make it Design System ready
    With the template inventory and knowledge of the code that’s behind the element we have to make the plan what to do with the element. Are there multiple different versions of the element but are they the same in basic? Then it’s time to define the standard element. Is the code fairly old and doesn't keep up with the standards we have for code quality? Then it’s time to refactor the code. Is the element complex but always used in the same way? Time to make a PHP widget for it. Or does it need all of these work-ups?
  3. Make a new version but keep the old one
    Depending on the impact of the changes, we make a new version of the element but keep the old version beside it to make sure the element keeps working in production. We don’t want elements breaking down in the applications while we are working on a new version. We mark the old version as deprecated so it doesn’t get implemented anymore during the development of the new version.
  4. Implement the new version
    Step by step we implement the new version, first in templates, then in the applications. We replace every occurrence until the old version is out of use.
  5. Delete the deprecated version
    When the ‘old' element or styling is disconnected from all the applications we can delete all the deprecated parts of the element.

By following these steps, we keep the impact of implementing new versions of elements as low as possible, and ensure a smooth transition in production.

What we gained until this point

  • More than design
    I started this project from my perspective on design and making designing UI’s easier and consistent. It grew to a much more integrated Design System in which we think about refactoring old code, using new CSS standards and building PHP widgets for the elements. Everyone from design to development can make use of the system.
  • Building proof of concepts fast
    While we are far from done I already see colleagues combining elements from the Design System together to make a quick proof of concept or develop an interface change without having to think about what elements should be used and how they should work.
  • Time to focus on improving and innovating
    Not having to invent the wheel over and over again gives us time we can spend focussing on what we really like, making innovative software. Improving and developing new features for which you don’t have to think about the basics like color, use of icons, basic interaction etc.
  • Easy to adapt - Creating less legacy
    With the new CCS pre-processor and updated coding standards for front-end it’s easy to adapt elements and make changes without creating new legacy in the applications.

What we haven’t fixed yet

Besides these challenges there are a still a few open wounds that we need to fix. I hope to tell you more about those challenges and how we fixed them in following blogs.

  • Controlled vocabulary
    From the initial design, through front-end development in to PHP widget development there is still inconsistency in naming elements.
  • Accessibility
    We made a first version of our Design System in patternlab which didn’t fulfil our wishes. All the elements are can be found in the templates but those aren’t easily accessible. This is something we hope to work on in the coming weeks.
  • Living
    Now we have the first version of quite some elements in the Design System we have to see and learn how updating will go and which new challenges will cross our path.


We still have a long way to go with our Design System and new challenges to face. How you handle these challenges depends on the kind of Design System you want, the kind of product you build and how your team works. But I hope to give you some handels to start your own. Because I firmly believe when you are building digital products specially on big scale it impossible to keep everything inline without a tool like this.

Join our team

Wanting to contribute to the Design System we are building? We are looking for a front-end developer who wants to share their vision and experience on front-end development and learn with us developing our Design System. 

Picture of Annemiek Scheele

Annemiek Scheele

UX/UI Designer