Building a Design System Workbench

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.

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. ​

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. ​

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 doesn’t require you to install node, or webpack, or anything really. — It’s a tiny executable (the zipped version is about 8 MB), that you double click to start. Just drop it into any folder and you are good to go, no technical knowledge or configuration required.

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:

• It allows for direct manipulation. — Using the Finder, you can quickly drag and drop things around, change names and structures, and experiment. DSK watches its directory and reloads automatically, so adapting your design system in real-time is possible.
• It supports any kind of filetype. — Because your design system in DSK is just files and folders, you can add any kind of file you have: just drag it into the folder. DSK uses text documents written in vanilla markdown as its main documentation format, but its “Assets” tab exposes all files that are added to an aspect. This is important because at the beginning of your design system creation process, you probably have all kinds of content flying around: Screenshots, images, Sketch files, notes, videos, prototypes, components, and so on. You should be able to collect all of it in a central location.
• It can be synced easily. — Any syncing solution that you normally use for your folders also works for DSK. Onboarding your team and allowing them to work on the design system might be as simple as sending around a Dropbox-link. And because of DSK’s file system watcher, when someone updates a document the changes are automatically displayed for you. This also makes updating DSK for a team easy: Just drop the new version into your shared folder and immediately everyone is using the latest version.

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

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 §

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 that make sure that users can create the highest quality of design system documentation:

• It can be hosted. — One of my favorite features of DSK is that anyone can start it on their own machine. But at a certain point, you usually want to make your design system documentation accessible to the whole company, without everyone having to run DSK locally. Of course, DSK can easily be hosted on a server and even comes with pre-built docker container images, if that’s your thing.
• There are documentation components. — The default format for writing documentation in DSK is vanilla markdown. But there are several “documentation components” built-in, that you can use in your markdown documents. They are purpose-built for the most common use-cases in design system documentation: there are components for displaying typographic systems and color specifications, an isolated “playground” for displaying components in a neutral way that supports interactive annotations and special components for telling people what they should and shouldn’t do. There is even a special component that can be used to embed layers live from Figma — change a component in your design system and the documentation updates immediately.
• It has full-text search built-in. — Design systems quickly grow large and navigating them quickly is key. DSK has a fine-tuned full-text search that is incredibly fast and comes with keyboard navigation support for pro-users.
• It can manage multiple versions. — When a design system has been in use for a while, there are often multiple products or teams using it. Often, not all projects have the resources to always be updated when something in the design system changes. For these cases, it can be vital that older versions of the design system are still accessible. While DSK can use any folder as a base, as the design system matures it is usually moved into a Git repository, so that there is a more structured collaboration. DSK is tightly integrated with Git and can recognize when its content is in a repo. Adding multiple versions is as easy as creating a tag in Git and telling DSK about it. DSK then displays a dropdown in its interface that lets users select the version of the design system that they want to look at (and search through).

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

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

• There is a versioned API. — DSK exposes all the contents of the design system documentation via a strictly versioned API. This means that it can function as a central repository for many other tools that access the information it stores.
• It supports custom frontends. — The built-in frontend of DSK (a React application) is completely decoupled from the backend — actually it uses the API I just mentioned to get all its data. DSK is built in such a way that the frontend can be replaced with a custom version completely. We have built design systems for various clients with DSK and have gone from projects where we only themed the built-in frontend with the client’s brand to building an entirely custom one from scratch. It is amazing to start with a local version of DSK running the built-in frontend in the first weeks and create the foundation of the design system there, and then end up with a hosted, customized fully-fledged design system documentation, without switching the tool.
• It supports custom documentation components. — When you build your own frontend, you can also add custom documentation components that you can then use in your markdown documents. This lets you add really easy-to-use custom features to your documentation that go beyond what an off-the-shelf solution might provide. We have for example built a custom icon picker that is searchable and also displays the grid that the icons are based on, or special elements that display how different components can be nested within each other and be configured.

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 §

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.

• DSK loves stubs and placeholders. — In DSK creating a placeholder for something that is yet to come is incredibly fast: Just create a new folder. That’s it! DSK encourages this kind of behavior. We’d rather see a preliminary structure filled with empty aspects, that gets changed and filled over time rather than just three or four perfectly finished aspects. DSK is a tool for collaboration and creating a shared understanding of structure early is one of the most important tasks when creating a design system.
• You can change your mind. — Because everything is kept in the file system, changing your mind is easy and fast. Just rename a few folders, move them about or change the order. You can turn your entire structure upside down in a few minutes. Nothing is set in stone, that’s why we use computers, right?
• Copies are cheap. — Again, everything is kept in a folder. Creating a copy of your design system and starting a separate instance of DSK to try out some things that you aren’t completely sure are a good idea yet is one of the most powerful ways to explore a design.

Because the final deliverable of designers is often a simulation of a finished product (whether 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 §

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:

• We prioritized features by our capabilities. — This way we could get a first working prototype really fast, which we could use to convince the team that building our own tool was worth the effort. Using technologies that we liked or that we had been wanting to try for a long time also helped us take care of our emotional resources.
• We worked with existing components and knowledge. — Whenever we could come up with a building block that behaved exactly as we wanted it, we took it even if it was slightly unconventional. This is why we completely went without a user interface for the backend: The file system and file editing software did exactly what we were looking for and there are many popular formats for documentation — no need to repeat the work.
• We practiced the “release early, release often” paradigm. — We started using the first version of DSK with our team within a few days after development started. That way we never built any features that turned out to be unnecessary: We always waited for a need to arise and then quickly added the necessary extensions. Because of sharing our design system via Dropbox, as described above, we could also update everyone’s version of DSK immediately. This way our team never had to care about updating and always got the latest features and bug fixes right away.

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