6️⃣How to document a design system

👋 Introduction

One thing that differentiates a design system from just a component library is its documentation. A design remains incomplete without guidelines and a centralised place from which it can be understood and consumed.

---

1️⃣ Create a reference website

Product teams will only be able to use the system properly if it’s well-understood and easily accessible. This can be accomplished by creating a reference website. A reference site primarily helps:

• Showcasing design system components and guidelines

• Making documentation easy to access and understand

Here’s an example of a component page on a reference website. Resist the urge to build a custom site for v1, and instead, use a non-code tool like Zeroheight so teams can contribute without writing code.

It’s important that your reference be unique to the specific needs of your organization, but here’s set of content that any design system user will probably be looking for. Use the structure below as a starting point for the sections your design system users may expect:

• Home

• Get started

• Guidelines / Patterns

  • Accessibility

  • Brand

  • Color

  • Error handling

  • Icons

  • Illustrations

  • Typography

  • Voice and tone

  • Etc..

• Components

  • Overview (containing component status page)

  • Accordion

  • Button

  • Breadcrumb

  • Card

  • Etc.

• Case studies

• Support

• Blog/News

• About

• Changelog

• Search

---

2️⃣ Further reading

Design System documentation best practices

"Making Design Systems Public," an article by Dan Mall

Structuring documentation in multi-brand design systems by Amy Hupe, content designer