Design Systems Handbook

Cover of the book Design Systems Handbook

I’ve been involved in the process of instating a design system twice. First, with the short-lived attempt to move the MediaWiki platform to mediawiki.ui. And second, replacing mediawiki.ui and whatever else MediaWiki was using to OOUI.

While the first attempt was limited to a small CSS file and KSS generated documentation, the second one came with a full-fledged demos page and a styleguide to go with it. MediaWiki is in the process of transitioning once again, now to Vue.js. This time though, things are different, the style guide remains in place, it is only the implementation of the components that’ll change.

So when I first heard about the Design Systems Handbook on the Design Better podcast I was immediately interested. Large legacy products like MediaWiki have long suffered from bespoke designs for every corner. Design systems that can scale-up help build products faster.

According to the book, a good design systems should have:

Design tokens





Visuals & Ornamentation






Voice & Tone



The design system should live in a repository of its own preferably with semantic versioning. This ensures that consumers can upgrade to newer iterations of the design system with full knowledge of what has changed.

Sometimes the system can be broken down into different packages. While this might be harder to maintain (fighting a hydra?) it has some advantages:

  • Packages can be loaded separately, improving performance
  • Different components can be upgraded as and when needed
  • Fewer big bad breaking changes

Having all your UI elements in one place (whether in one repository or spread across multiple) means that you can test them together. This could be accessibility tests, visual regression tests and even functional tests if you have fully working components as part of the design system.

The style guide is the manual to the design system you’ve built. It should ideally be generated from the code of the design system itself. This is possible when using tools like Storybook or the now defunct KSS.

With these tools you can get started with a document listing all components and elements, but as the guide grows this might not be enough. At this stage, it is a good idea to show this style guide to its internal users β€” designers, front-end developers, PMs, accessibility experts β€” and collect feedback on what is missing and what could be improved. In the end, the style guide is meant for their use.

The most exciting part of the book were the possibilities that having a style guide could open up in the future. Imagine a system that could understand the different parts of your style guide β€” its components, how and where they’re used, in which layouts and using what data. This, coupled with real-world examples of how the components are being used in your products, could allow this system to create predictive user-interfaces. Just tell this systems what you want, and a user-interface magically comes out. This is probably a bit far into the future, but I’d love to be able to experiment with this, maybe even using Wink!

Leave a Reply

Your email address will not be published. Required fields are marked *