Building a Design System Workbench

21. April 2020

When we were looking for a tool to build a design system with, we couldn’t find one that fulfilled our needs. So we built and open-sourced our own: DSK, short for “Design System Kit”. Throughout the development we stuck to a few principles, which guided all of our decisions. While the secondary goal of this post is to explain DSK’s features, its primary goal is to give an example how abstract principles can guide concrete product decisions.

The most common question people ask when we talk about DSK is “By and large, isn’t it like any other documentation website generator?”. By and large it may be — but in detail, it is not. DSK is different from other tools, because we chose to embrace certain principles more than others. This is an exploration of these principles.

This is the written version of a talk I gave together with Marius at the code.talks conference in Hamburg in the fall of 2019.

What sets DSK apart is that we built it not as a tool to generate a website from a bunch of documents, but as a tool to write a bunch of documents to generate a website from. This might sound like hair-splitting but has in fact grave consequences for the users of DSK. Because it is built as a workbench, not a documentation generator, every product decision was made with that image in mind. This results in a product that is optimized for process first and for outcome second. It makes DSK a fundamentally human-centered tool.

Designed for Process

When we started looking for tools to help us build a design system from scratch, we discovered that there are many tools that help you with the outcome, but they care little about the process. When we say outcome, what we mean is “We want a documentation website for our design system, and it needs to be nice and shiny!”. That was certainly true, but it also wasn’t our primary concern at that moment. Instead what we thought was “We need to build a design system, and we’re creating it from scratch!”. It felt like people were offering us display cabinets, when we were looking for a sturdy workbench. A similar distinction was introduced by Brad Frost in “the workshop and the storefront”.

The second thing that bothered us, was that all these tools — built by engineers — were mostly focused on the needs of engineers, rather than the whole team. (Coincidentally it is also usually engineers who have trouble understanding what makes DSK different from other tools.) As the design system movement has historically grown out of the CSS pattern library movement, it is still often the case that design systems and component libraries are treated synonymously. However not every design system has at its core a set of React (or Vue, or whatever) components. This is why in DSK we refer to “aspects” of a design system, rather than “components”.

Get Started Right Away & Use What You Have

So our first principle became “Designed for Process” — DSK tries to be valuable for the whole team, from the first moment on. This starts with getting it to run.

DSK in its natural habitat.

The DSK binary takes its surroundings as input: Whatever folder you drop it into is considered the root of your design system documentation. The structure of your design system is created by adding new folders in the file system. DSK takes these folders and displays them in an easily-navigatable frontend that is optimized for readability and giving an overview at all times. Using the file system as a backend has several benefits:

The goal is to get you into a state of “doing”, rather than “setting up” as quickly as possible.

Low Floor, High Ceiling, Wide Walls

Very early on we realized that, as cheesy as it may sound, DSK is not a website generator, but a tool for supporting creativity. So we looked around to see what other people had learned about building these kinds of tools. One of the ideas that influenced us the most was the concept of “Low Floor, High Ceiling, Wide Walls”, by Seymour Papert and Mitchell Resnick (creators of the Logo and Scratch programming languages for children respectively) of MIT Media Lab.

For a technology to be effective, [Seymour Papert] said, it should provide easy ways for novices to get started (low floor) but also ways for them to work on increasingly sophisticated projects over time (high ceiling).

For a more complete picture, we need to add an extra dimension: wide walls. It’s not enough to provide a single path from low floor to high ceiling; we need to provide wide walls so that kids can explore multiple pathways from floor to ceiling. Mitchel Resnick, 2016 [original post is down]

It is easy to build a tool that accomplishes one of those things, but it takes determination to adhere to all of them, even as you add more sophisticated features. But lose one of them and the quality of the work that can be created with your tool is bound to drop significantly.

Low Floor: It’s Easy to Get Started

DSK’s low floor is guaranteed by all the features I mentioned so far: No technical knowledge, no installation, no database, no configuration necessary. All you need to know as a novice is how to create folders and text files, and you can start building your design system.

High Ceiling: It’s Scalable

A purpose-built documentation component for documenting typographic systems.

But just because we care about process first, outcome second does not mean we don’t care about the outcome — quite the opposite. Catering for the needs of more mature design systems are several features which make sure that users can create the highest quality of design system documentation:

It is important to note that all these features are additive — you don’t have to use any of them, if you are not ready for it. The high ceiling does not compromise the low floor.

Wide Walls: There Are Many Possible Ways of Doing Things

The last property that tools that support creativity should have, is that they allow for many different results, rather than prescribing a predefined solution.

When evaluating the use of creativity support tools, we consider diversity of outcomes as an indicator of success. Resnick et al., 2005

A custom icon picker.

We want DSK to be helpful for a lot of projects. Because of this it comes with a couple of strong opportunities for customization.

In the end, no one might even guess that your design system documentation runs on DSK. We think that’s a good thing.

Designed for Uncertainty

Just the way designers work.

We feel that most design tools are particularly bad at dealing with uncertainty. That’s a shame, because uncertainties in product development have to be anticipated. In fact, they should even be sustained for a while! Resisting immediate clarification, trying out different solutions and accepting some things get filled out later, when more information is available, usually leads to better products. Design tools should support this, rather than acting as if uncertainty doesn’t exist.

DSK is built for content that is uncertain, because when we started our project, we felt the tools that present your documentation as if it is always finished were being dishonest. What we needed was a place for fragments; a place that allowed for chaos, but also for structure; a place with flexibility to adapt when we change our minds; and most crucially a place to “shape” the design system — much like you would shape a piece of wood: one cut at a time.

Because the final deliverable of designers is often a simulation of a finished product (wether in the form of static screens or a prototype) it is easy for designers to fall into the trap of simulating finality where it isn’t required yet. Let’s change that and embrace uncertainty!

Resourcefulness

Our best decision: using the filesystem.

This principle is more an inward principle than an outward one. DSK was a by-product of developing a design system from scratch. Because there was no extra budget for it, being resourceful was crucial to getting it to run in the first place. If you are in a similar situation, these are the things that worked for us:

When building a new custom tool in a competitive space you quickly get accused of suffering from “Not-invented-here-Syndrom”. Being resourceful gives you a chance to prove that building a new solution is actually valuable and your ideas are worth their salt.

Being Principled

During this whole process — we have been developing DSK for over two years now — we noticed that the most important principle might be to be principled at all. Whenever we had to make a decision about a feature or were considering how to implement something, we spoke about our principles and what would be the solution most in line with the kind of tool we wanted DSK to become. That way, principles can guide you and help develop a coherent product. We believe that following the right principles will shape your product in a way that makes it more useful and wholesome for your users.

We also learned that some principles are worth sticking to through the whole lifetime of a product, but sometimes it’s time to let go. Letting go of “low floors” seems to be the easiest thing you could do, but we believe it may be the most important one to stick to. Other principles are more or less optional: We started out with a strict “no configuration” policy, but at a certain point noticed it was holding us back. So we switched to a “some configuration, but none necessary to get started” policy and have been very happy with it since.

The most important lesson might have been that we didn’t start out with our principles in mind. We recognized that these were things we cared about during the process and then decided that they were something we wanted to keep around to guide us. You don’t need a principle to start: discover them.


Thanks to Marius Wilms for writing and giving the talk with me and to Micha Wiebe for inviting us to speak. A video of our talk is available here. The photo of me at the top of this post is © michaelreitz.de

Imprint