Documenting Design Systems with the Teachable Engineering Team

Documentation is one of the three pillars of a Design System, alongside Code (React) and Design (we use Figma).

Documentation is crucial to design system adoption. It consolidates usage guidelines, design, and code to help product teams ship faster, leading to more consistent user interfaces. The end result is customers receiving a more seamless experience across the website.

Design System documentation should explain design decisions, design patterns, and usage guidelines. For developers, it is important to show component variations, examples, and props. For both teams, consistency is key. Storybook and Figma need to be in alignment to avoid confusion and unnecessary work.

Keys to Good Documentation

At Teachable, the Design System team strives to create great documentation by keeping the following goals in mind:

• Know your audience
• Make it consistent
• Make it comprehensive
• Prioritize accessibility

Know Your Audience

Developers are the main users of our Storybook documentation, so we focus on developer productivity. To do this, we include all the variations of a component along with code snippets. Developers can then find the variation they want and quickly copy the code. A side benefit of doing this is that it doubles as a way for our team to test our code by looking through each example.

We also make use of Storybook’s “ArgsTable,” a Storybook feature that automatically generates component args (or props) tables. Developers are able to view all the props and have controls to change the default story to see what each prop does.

Finally, we always add a note if there is some unexpected functionality, usage, or variant that might not be obvious to the developer. An example is the Toast component — we add the following message to help ensure that developers use Toasts for their intended use and not as a catch-all message component.

For our Loader component, we use a Container component.This example required some extra code that we make note of.

Make It Consistent

In the past, Storybook and Figma have gotten out of alignment. The biggest problem we had was updates in one tool not being reflected in the other. Inconsistency between the two led to designers creating components that didn’t exist, and developers implementing code that didn’t match the design. This then led to lots of confused Slack messages about what components we have and don’t have. Finally, when the library was first built, development speed was prioritized over detailed documentation. As a result, many components had only one or two examples, or, in some cases, none.

We realized these issues were a big problem because they affected design adoption, developer productivity, and brand consistency. We are now finishing a project where we synced up Figma and Storybook and improved documentation to fix these issues. Here is how we made each Storybook page more consistent:

• We have the same layout on each page, starting with a component name and description that matches the Figma component.
• The first example is the most popular, or default, version of the component with the code snippet.
• Next, the ArgsTable shows all the props and lets developers control the default version to see what each arg can do.
• The rest of the page is all examples. We try to cover as many different variations as possible, making it easier for the developer to find the code variant they need and for our team to quickly check and test components.

Make It Comprehensive

I mentioned in the previous section how we have examples of all variants on a component page. But that isn’t the end of making the documentation comprehensive. Besides the component pages, we have several other pages that help product teams know about everything the Design System is capable of.

Cheat sheets for our utility CSS classes

We have a set of utility classes that developers use and have a naming convention for. Sometimes it is easier to see them all on a page and copy the one you need.

FAQ Page

Our FAQ answers questions from “Who do we contact about a bug?” to “What breakpoints do you use?” and “What Browsers do you support?” Anytime we get a question in one of our slack channels we check whether we should have it as a FAQ question. The answer is usually yes, our motto… document everything.

Component Status Page

This page has been key to showing component availability and project progress. While very important to new design systems, it has proven very beneficial to our existing one as well. As a side note, you do not have to show the same status forever. If you are working on a documentation project, you can show the status for that project. Once completed, remove or change a column to the next project.

Other ideas for making your documentation more comprehensive include:

• Change Log — Important because not everyone knows about or will go to Github. Also, ours is specific to the DS so it is easier to see changes.
• Color Palette — We support css and js color variables.
• Icons — We list out all the icons we have and how to use them.
• Typography — Not only each typeface, but also instructions and usage.

Prioritize accessibility

The final area of documentation I want to talk about is accessibility. As part of our documentation improvements, we are adding accessibility guidelines to each component. Ideally the component itself is 100 percent accessible, but unfortunately this is not always the case:

• A component might be accessible, but combining it with another can lead to the implementation being inaccessible. This could be a problem with design systems that consist of atomic components combined to make “molecules.”
• A component might be flexible, and while the default way of using it is accessible, it is possible to use it in a way that is not.
• Not all developers are familiar with accessibility. Adding guidelines helps everyone.

Take these issues into account and make sure your component is accessible, and document how to use it. Your examples should all be accessible as well, since users might copy the code without thinking. For example, we have a Label component separate from Input. On the Input page, we make sure to include Label with all the code snippets and make a note of why we do that.

Hopefully we have given you some tips to better document your design systems so that it will increase adoption and make it easier for product teams to deliver code. Come back for the next article in the series by Kristin Moser on integrating Storybook into our CI pipeline.