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 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?
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 wireframingAny 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).
- 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 templatesTemplatising your documentation is enormously useful. Starting with a template makes generating new pages far easier, and ensures a consistent experience across your design systemBuild reusable modulesContent 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 updateA 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.
- know where to go to find what they need
- understand what to do when they get there
- be engaged and want to come back
- 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).
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
