Design system maintenance — sharing markup between applications
A little over 2 years ago we decided to switch to a modular UI design methodology and a style guide driven development process.
In the beginning we spent a lot of time discussing how we should build our design system, what components it should include, what CSS architecture to use and how to create a template layer with the vision to achieve the holy grail design system.
Now, we are in a state where our component library, processes and the template framework are relatively stable. Instead, one of the more time consuming tasks has been to keep the markup of each application in sync with the markup in our component library.
The markup is distributed between many different applications, all with separate code bases.
As Brad Frost writes in his book Atomic Design:
Atomic Design: the Book, chapter 5
Our ecosystem of applications
Since so many applications are running on the same web site our situation doesn’t really allow us to use versioning as an effective tool to manage updates. I believe that this situation might differ from what many others are dealing with.
To explain our situation, compare the following two ecosystems of applications distributed between different web sites.
The first image shows an ecosystem with many sites (on perhaps many different platforms) where each is home to a small number of applications. This means that there are fewer applications that need to be bumped up to the next version of the design system at the same time.
The second image shows an ecosystem much like ours, where you have a few large websites/portals that is home to many different applications, each with their own code base. All applications within a website/portal share the same design system resources.
Even in our situation, it is of course possible to link up a different version of the design system to our different portals but this still means that we have about 50 applications for each site that require a simultaneous update and deployment.
Templates — to relieve some of the pain
In the beginning of this post, I mentioned our template layer which adds an abstraction layer on top of our component templates. This template layer is a great help. It means that refactoring of HTML markup can be done at template level — in a single place.
All applications (including the component library in the style guide) share the same templates so a change in HTML markup in the template is automatically reflected in all our applications the next time we deploy the component framework templates.
The problem, for us, arise when we need to update the template XML, which we have been forced to do more often than we would have liked (and perhaps expected).
It can be larger refactoring of the components content model but also small things like streamlining the naming of content elements in a template, e.g. we want to change name=”title” to name=”header” in the template for the component “message”.
/* Application code for displaying a message using the message-template. Written in our XML template language. */
<gbg:element name=”title”>Of Dominion After Land</gbg:element>
So Saw second every fifth likeness.
We have discussed different alternatives to facilitate the process of updating markup. And frankly, we are not really satisfied with any of them but let’s look at three of the options we have discussed.
Introducing a versioning number per component
Although this is a possible solution, it adds a complexity to the system that’s otherwise not necessary. And also, if you’re not careful you might soon have another maintenance issue on your hands.
Linking up different versions of the design system per page
Another solution that could work in theory is to let each page decide which version of the design system resources to load. This also mean that we need to be able to use different versions of the template framework on different pages.
One obvious downside is that a user, during a visit, might have to download several versions of the resources. It is also problematic if two different applications on a single page needs different versions.
So, for many reasons, this approach does not seem like a way forward.
Updating applications one component at the time
The approach we are using now is to batch update all applications that uses a specific component and then simultaneously deploy these to production together with the latest design system resources and component framework templates.
The downside is that we, over a short period of time, might have to do several deploys of a single application if there are markup for several components that need refactoring (since we update only one component at the time).
To update markup for more than one component at the same time increases the the number of applications that we need to update simultaneously, e.g. all applications that uses either component A, B or C.
Regardless of whether you use a template language or plain HTML in your applications it is still a difficult task (or at least time consuming) to keep markup distributed over many different applications in sync with a central design system.
If you have many of those applications running on the same website it adds to the complexity.
Are you maintaining a design system and have you experienced similar problems. We’d love to here about it!
This was part 7 in the publication: Our Story: Building a component library