Design systems 101

Design systems are powerful

They make workflows way smoother. They help designers and developers collaborate. And they make sure the products you build are consistent and a pleasure to use. All of which means they will save your business time and money, make you even more efficient at building things, and make those things you build even better.

Sounds great, doesn’t it?

But to create a successful design system, you need to invest a lot of time and effort upfront to make it work. Long before you reap the rewards. And in particular, you must invest in creating great documentation if you’re going to get the most (or really, much at all) out of the end product.

Thankfully we’ve been there and done that. So we’re here now to tell you how you can build great design system documentation for yourself.

Wait, what even is a design system?

A design system is an essential tool for anyone who really cares about design. (Which you should, if you don’t already. Companies that invest in design create products that go to market twice as fast, and reduce development time by 33%.) But you can’t implement one without documentation.

Google ‘design system’, and you’ll probably come across a definition that looks something like this:

• It’s the single source of truth for everyone at the company when it comes to design.
  

• It’s a vault of asset libraries (we have libraries for brand designers, UX/UI designers and frontend developers).
  

• It’s a collection of guides to things like UI principles and content writing.

But maybe it’s more accurate to say these things are what a design system can be.

Maybe you really just want a library of components that anyone can access wherever, whenever — and that’s fine. A good design system is built around what your company actually needs.

Our own design system, Prisma, was born in 2017. Back then it was just a rudimentary collection of components in Sketch, and the hopes and dreams of our designers.

But as we scaled, built more products and hired more people, it was getting harder to maintain design consistency. So in 2019 we kicked it up a gear. We built a crack team of designers, copywriters and engineers to take our system from side project to widely-adopted design philosophy.

Our first port of call: discover how to make documentation that satisfies everyone it serves.

But documentation is just documentation, right?

Wrong. Let’s get this straight from the start: good documentation isn’t just a “nice to have” for a design system. A design system absolutely lives and dies by it.

It’s the guide to action for your design system. It’s critical if you want your components to get used properly, all of your content to be on-brand, and your design rules and principles to be clear.

Documentation turns a design system into something that people can actually understand and follow. And that’s crucial. Because getting the documentation right drives adoption. Adoption is what makes a design system really successful. And when adoption rises, your design teams produce consistent, quality work. And when your design teams produce consistent, quality work...

I get the picture. Where do I start?

You gotta do the research. It’s important to see what’s out there before you get started. Looking at other systems will give you vital context — their information architecture, their site navigation hierarchy, the structure of each page.

Atlassian’s design system, Google’s Material Design and IBM’s Carbon all have documentation that really inspired us. They’ve got impressive scope, impressive detail and elegant information architecture — everything we wanted to get absolutely perfect. (No pressure.)

We did borrow elements from other systems when we created the Prisma documentation, and you’ll probably do the same. But we couldn’t just copy and paste a single system. Of course we couldn’t. None of them were purpose-built for what we actually needed.

So when we were choosing which elements to borrow, which to build from scratch and which to leave out altogether, this is what we found it useful to ask:

• Who is going to be using the system, and what are they going to be using it for?
  

• How do you make sure your documentation is both super clear and super detailed?
  

• How do you make sure your documentation can scale as your company — and your system — does?
  

• How do you make sure your users can effortlessly navigate to what they need to know?
  

These prompts will help you build the foundations of your website, but then there’s the most important question of all:

How do you make sure people will actually bother reading it? Here are a couple of top tips.

Understand what your reader needs

You need to work out which content is most important to you, and allocate time and resources accordingly to produce that content. Maybe your company produces a lot of written work, so it needs extensive writing style and tone of voice guidelines. Maybe your priority is visual design, so the components library should be front and centre in your documentation.

In our case, the product designers needed pages on specific components like buttons — not to mention component libraries, so they could actually start building. Without these features, the docs wouldn’t be useful for them.

Balancing clarity with necessary detail is tricky, and there’s no single answer for where the balance lies. But researching what your company really needs design-wise will help. Your docs should always be an effective guide to action for your readers. So always put your reader first whenever you create any content.

Create your own writing style (and stick to it)

You might also want to adjust your documentation’s tone of voice to keep it engaging. After all, documentation is written for people, so it’s likely to benefit from a human touch. We gave Prisma a friendly, approachable voice to make our docs a bit more appealing. Maybe even think about including a joke or two to keep users awake — as long as it doesn’t distract from the important stuff.

So now you’ve figured out what’s going into your documentation. Time to think about how you’re actually going to build the thing.

How do I build the thing?

The website that hosts your documentation should ideally be custom-built to fit the needs of your design system (which should definitely be custom-built to fit the needs of your company). Solutions we’d used previously limited the complexity of our content, and we couldn’t track the site’s performance with analytics. So moving to a custom-built website — where we could structure the site and pages the way we wanted, and could create the design system that worked best for us — was a no-brainer.

Plus, attractive visual design also makes pages easy to read, and easy-to-read pages… you guessed it… boost adoption.

Begin by wireframing

Any website design needs to start with a wireframe. And like everything else about your documentation, you should be iterating and refining your wireframe over time.

We started off by sketching pencil and paper wireframes, before cleaning them up and creating final mockups in Sketch (though we’ve moved all of our assets into Figma since then).

Here’s our list of top things to consider when wireframing your design system:

• Ease of navigation: information should be organised intuitively across all pages, so a user can find what they’re looking wherever they are
  

• Clarity: information should be broken up into readable chunks
  

• Accessibility: language should be easy to understand even for non-designers, colours should have a high contrast ratio and fonts should be easy to read
  

• Ease of understanding: examples, ‘dos/don’ts’ and illustrative images should help make sure everyone understands how to use each component and guide
  

And how do I make sure it scales?

It’s crucial to make sure your docs are flexible and scalable, because they will need to change at some point. But future-proofing doesn’t have to be hard. You can help out future-you with a few key considerations. For a start:

Create templates

Templatising your documentation is enormously useful. Starting with a template makes generating new pages far easier, and ensures a consistent experience across your design system

Build reusable modules

Content elements like banners, cards and tooltips organise information and keep it digestible, so it actually gets understood. These elements can then be added to pages as and when they’re needed, making adding info effortless.

Make it easy to update

A simple content management system is crucial. We chose Storyblok because, being ‘headless’, it let us choose exactly how we wanted everything to be presented. It also included a visual editor, which allows anyone (even non-developers) to make updates whenever they need to.

At the end of the building process, and if you’ve done your job right, everyone who visits your design system should:

1. know where to go to find what they need
   

2. understand what to do when they get there
   

3. be engaged and want to come back
   

4. build products, presentations and more that are on-brand and delightful.
   

Speaking of adoption…

We consider our design system to be a product — just one we use internally. So we market it.

We keep everyone informed with an internal newsletter, update everyone with Slack posts, and hold onboarding sessions and workshops. Prisma has its own brand, with its own tone of voice and visual identity. And we outright show people how they will benefit from using our system.

The results?

If you’re a designer, people will stop asking you the same basic questions over and over again. People can self-serve and stop disrupting your workflow.

What’s more, you’ll save a lot of time on design and engineering processes. This means you save money. Potentially a lot of money. Lily Dart reports that Constellation, the design system for Lloyds, saves £190,000 per project.

To maximise these benefits, you should create KPIs to measure the success of your system. Starting with how many people are visiting the site. But be warned: this doesn’t necessarily mean they’re actually using the system.

To measure that, you’ll need to track other numbers alongside it — like session length for each user, or how many people are going to design meetings, or the amount of requests processed compared to PS (pre-system).

The KPIs for your design documentation will need almost as much thought as the docs themselves. And sometimes they might be tricky to pin down. That’s normal.

But what if the documentation doesn’t get used?

If people don’t use your documentation, ask them why.

If someone uses a component in a way our libraries don’t normally allow, we follow up. And if people feel the need to detach components, we explore whether there’s something missing from the documentation. Sometimes we have to revise and update components, or add new ones.

Remember: a design system is never truly finished, and you should build documentation to make sure improvements are easy to implement. It will (and should) change as its users’ needs do. If you’re measuring the success of your docs with KPIs, you can easily pinpoint which areas need work and change them for the better.

Recently, we went through a round of user testing to see whether we should change the information architecture of the docs. We figured out which parts of the site are hardest to navigate, and we’re about to make changes to the structure based on our findings.

You should go back to the documentation regularly to evaluate how well it’s working. Frequently and actively gather feedback from the people who are using it. And keep that big question in mind with every new page, component or novel-length collection of documentation: How do I make sure people will actually bother reading it?

Because without excellent, widely-read design documentation, your design just won’t be as successful. And good design equals an unparalleled experience for the customer. Which is, ultimately, why design really matters.

We're hiring! Take a look at our open roles