Design Systems Documentation in a Wiki

I’m reading the excellent book Design Systems by Alla Kholmatova and it’s been a great resource so far. I would consider it to be a higher-level companion to Brad Frost’s Atomic Design book, which I read early this year. Neither of these are very long books, and as a relatively new freelancer I love the freedom of getting to buy books to improve my skills as a business expense.

The idea behind this Design Systems book is to provide a lot of the answers to “why” are design systems important, and “how” to start with certain mental exercises before even creating a design system. The prep work in the foundations section of this book is really excellent and inspired me to look for another new way to implement a design system for a client.

design systems

As I work with different customers I think about the best way to provide deliverables to each team. I’ve created big PDF’s full of visuals when that is the best option, and I’ve created styleguide web apps stored in a git repo… but, I really like the power and flexibility of the Wiki for detailed and in depth documentation. Wikis are easy to share with a team and collaborate in, easy to search, and easy (easier) to maintain.

Recently I had the opportunity to use the excellent Confluence from Atlassian with a new client and it is a great tool for building a pattern library. I’m calling it the “UX Library” and it contains the following major categories:

  • Design Principles
  • Personas
  • Functional Patterns
  • Perceptual Patterns
  • Modules
  • Vocabulary and Tone

There are two great features of Confluence that I’m using, (not sure if you can do this MediaWiki or DocuWiki)

First, creating Page Templates for new patterns of certain types to make it clear what each pattern should contain.

current template screenshot

Second, I’m creating Clickable User Journey diagrams that map to the specific pattern or module that the diagram box the user is looking at.

pattern map diagram

These give the internal audience a visual way to quickly find the overall flow and the specifics of each interaction.

All together this makes a wiki a great tool. It becomes a living, and maintainable UX spec for the entire product or across the company with multiple products implementing similar patterns.