Skip to main content

Starting documentation for our design system

This post is the third in a series to document the challenges and joys of organizing and implementing a design system for We started by auditing our design system, which you can read about here.

After the tedious process of auditing our resources, UI, and processes, our next step was to create an organizational foundation for our design system. We needed to find the right tool to house the system and start documenting what we had.

1. Finding the right documentation tool

The concept of documenting design systems is just starting to gain serious traction in the design community, which means that the tools are a little behind our needs. We had to be flexible in our requirements because there was no perfect tool. Here’s what we chose to prioritize:

  1. Is the documentation simple to edit, for technical and non-technical team members?
  2. Does the tool have a broad text search?
  3. Is it possible to integrate our ember library?
  4. Is the UI simple and easy to use?
  5. Does it support lots of different kinds of content?
  6. Is the tool inexpensive?

And here’s what got left out:

  1. Is it possible to integrate Figma with the tool?
  2. Does it support design system specific content, like color swatches?

We evaluated 10 different tools, given these priorities.

Zeroheight and Gitbook were out best options, and unfortunately Zeroheight ended up being very Sketch-focused (since writing this, Zeroheight has added a Figma integration). Even though Gitbook is meant for all types of documentation, not just design systems, it was the right choice for our small team given the criteria.

2. Information Architecture for Gitbook

The next step was deciding how we would organize our design system documentation. There are a lot of ways to do it, and instead of making the choice for the team, I asked 5 members of our product team (designers, developers, and PMs) to do a card sort exercise to group and name the different aspects of our system that we wanted to document.

As it turned out, most of us chose similar categories and terminology. We all agreed that we should separate foundational styles from components. And that components could at least be divided into ‘Atoms’ and ‘Molecules’, ‘Atoms’ serving as the irreducible components and ‘Molecules’ as the more complex. We ended with these high level sections for the documentation.

3. Documenting our foundational styles

Once we had the right tool, it was time to document the foundational styles for our product, specifically:

  1. Color
  2. Typography
  3. Patterns & Illustrations
  4. Iconography
  5. Spacing & Layouts
  6. Responsiveness & Screens
  7. Depth & Division
  8. Copy
  9. Our Mascot (named Ami)

We split up this responsibility between the 3 designers. As it turns out, we were also doing a rebrand during this time, so a lot of the documentation ended up being aspirational — hoping to guide our UI to a similar style as our new brand.

We looked at design systems like Atlassian, Carbon, and Material to help determine what each page should look like. We didn’t create templates because each of these subjects requires very different information.

Color as an Example

One of our designers, Richard, took on the color documentation and did an excellent job creating useful guidelines. He divided each of our colors into three sections: Palette, Accessible Combinations, and Examples, which you cans see below.

It was important for use to make documentation that would work for both developers and designers, so we reached out to the development when building these pages, to ensure we included helpful code snippets or SCSS variables.

What’s next?

Documenting our foundational styles gave us enough understanding of the current system to start working on some design principles to guide the rest of our work.