Chapters

Chapters

Chapter 6

Documentation

Documentation

Documentation

It's time to create a "map with pin-points" and instructions on where to find things. Documentation is where we collect assets, source files, code, design principles, animation styles, and guidelines for using the components.

It's time to create a "map with pin-points" and instructions on where to find things. Documentation is where we collect assets, source files, code, design principles, animation styles, and guidelines for using the components.

It's time to create a "map with pin-points" and instructions on where to find things. Documentation is where we collect assets, source files, code, design principles, animation styles, and guidelines for using the components.

Documentation is useful only when people know how to use it, and we often need to remember that. We are talking a lot about people working on the design system but not design system consumers. They need to know where to find the detailed structure of the assets, variants, hacks for optimized work, or recommended plugins. Have that in mind when choosing a platform and writing the instructions.

Documentation is useful only when people know how to use it, and we often need to remember that. We are talking a lot about people working on the design system but not design system consumers. They need to know where to find the detailed structure of the assets, variants, hacks for optimized work, or recommended plugins. Have that in mind when choosing a platform and writing the instructions.

Documentation is useful only when people know how to use it, and we often need to remember that. We are talking a lot about people working on the design system but not design system consumers. They need to know where to find the detailed structure of the assets, variants, hacks for optimized work, or recommended plugins. Have that in mind when choosing a platform and writing the instructions.

Usually, teams that have low design system coverage find all sorts of excuses. For example:

Usually, teams that have low design system coverage find all sorts of excuses. For example:

Usually, teams that have low design system coverage find all sorts of excuses. For example:

We were not sure if we could detach the component,

so we quickly created something new.

We were not sure if we could

detach the component,

so we quickly created something new.

We need guidelines for complex use-cases.

We need guidelines

for complex use-cases.

We need guidelines for complex use-cases.

We came up with a different scenario that
was not included in the specifications.

We came up with a different scenario

that was not included in

the specifications.

The rules are so strict we can't be creative anymore.

The rules are so strict

we can't be creative anymore.

As you can see, all of them lead the documentation. So its primary goal is to provide guidelines for all consumers (employees).

As you can see, all of them lead the documentation. So its primary goal is to provide guidelines for all consumers (employees).

As you can see, all of them lead the documentation. So its primary goal is to provide guidelines for all consumers (employees).

Everyone needs access, and everyone needs to understand how to use the documentation.

Everyone needs access, and everyone needs to understand how to use the documentation.

EVERYTHING SYNCED

EVERYTHING SYNCED

EVERYTHING SYNCED

A Single Source of Truth?

A Single Source of Truth?

A Single Source of Truth?

A single source of truth in design systems is like having one special rulebook where we save all the rules and all the information is regularly updated

A single source of truth in design systems is like having one special rulebook where we save all the rules and all the information is regularly updated

A single source of truth in design systems is like having one special rulebook where we save all the rules and all the information is regularly updated

For example, if I change the primary red color in Github, the change is automagically pushed and updated everywhere we use it.

For example, if I change the primary red color in Github, the change is automagically pushed and updated everywhere we use it.

For example, if I change the primary red color in Github, the change is automagically pushed and updated everywhere we use it.

Your design system
Development
iOS
Web
Marketing
Design
User
Your design system
Development
iOS
Web
Marketing
Design
User

How to choose the right tool for the documentation?

Two-way syncing is one of the most complex challenges, especially when working with multiple platforms (Web, Android, iOS).


The easiest shortcut for having a single source of truth for foundations is to use Tokens Studio (rebranded Figma Tokens plugin). But we still need to have the documentation site. Let's go through specifics.

Two-way syncing is one of the most complex challenges, especially when working with multiple platforms (Web, Android, iOS).


The easiest shortcut for having a single source of truth for foundations is to use Tokens Studio (rebranded Figma Tokens plugin). But we still need to have the documentation site. Let's go through specifics.

Two-way syncing is one of the most complex challenges, especially when working with multiple platforms (Web, Android, iOS).


The easiest shortcut for having a single source of truth for foundations is to use Tokens Studio (rebranded Figma Tokens plugin). But we still need to have the documentation site. Let's go through specifics.

Start by answering these questions:

Start by answering these questions:

Start by answering these questions:

How will other teams contribute?

How detailed will your instructions be?

In what form will you add your code snippets?

Do you want to include the code

or embed stories from Storybook?

Will you provide live previews?

Do you want to include the code

or embed stories from Storybook?

Do you want to include downloadable assets?

Do you want to include

downloadable assets?

Who are our consumers?

How many design system maintainers do we have?

How to choose the right tool for the documentation?

Also, consider the following:

Ease of use

How easy is it to embed designs, code, downloadable assets, connect pages, etc.

Integration with other tools

How easy is it to connect with other tools? Is it plug-and-play, or is there much going back and forth for things to work?

Collaboration

How easy is it to add new team members? How expensive is it to add the whole team? Can you add specific rules? Can you lock certain content (for public use, for example)?

Built-in resources (templates, guides)

Does the tool provide any guidance for setting up the whole ecosystem? Do they offer some templates for writing or structure for adding content?


Does the tool provide any guidance for setting up the whole ecosystem? Do they offer some templates for writing or structure for adding content?

Okay, so many people will say: "Figma ticks all the boxes." Weeeelll, not so fast. You can include many descriptions with plugins such as Gist, but adding code snippets or downloading options is impossible. That's why I don't understand why so many teams stay at the UI kit level (even when they have resources).

Okay, so many people will say: "Figma ticks all the boxes." Weeeelll, not so fast. You can include many descriptions with plugins such as Gist, but adding code snippets or downloading options is impossible. That's why I don't understand why so many teams stay at the UI kit level (even when they have resources).

Okay, so many people will say: "Figma ticks all the boxes." Weeeelll, not so fast. You can include many descriptions with plugins such as Gist, but adding code snippets or downloading options is impossible. That's why I don't understand why so many teams stay at the UI kit level (even when they have resources).

LEVEL UP

LEVEL UP

LEVEL UP

How mature is your design system?

How mature is your design system?

How mature is your design system?

My suggestions for choosing the tool based on your org size.

My suggestions for choosing the tool based on your org size.

My suggestions for choosing the tool based on your org size.

When you are starting fresh

When you are starting fresh

When you are starting fresh

If you are new to the design systems and just making your way through the first year, I would advise you to choose from "off-the-shelf solutions" (Zeroheight, Supernova, Knapsack, Specify, Backlight).

If you are new to the design systems and just making your way through the first year, I would advise you to choose from "off-the-shelf solutions" (Zeroheight, Supernova, Knapsack, Specify, Backlight).

If you are new to the design systems and just making your way through the first year, I would advise you to choose from "off-the-shelf solutions" (Zeroheight, Supernova, Knapsack, Specify, Backlight).

Why? In the first year, you will make a lot of mistakes. It could be naming conventions, architecting the whole system, or creating a contribution model. A lot of stuff will happen, and it will be overwhelming. Having an app that removes the decision fatigue for building a custom CMS will give you more time to think about the important stuff. After you figure out what you need, invest in an advanced documentation site. But don't make it custom just because the internet says so.

Why? In the first year, you will make a lot of mistakes. It could be naming conventions, architecting the whole system, or creating a contribution model. A lot of stuff will happen, and it will be overwhelming. Having an app that removes the decision fatigue for building a custom CMS will give you more time to think about the important stuff. After you figure out what you need, invest in an advanced documentation site. But don't make it custom just because the internet says so.

Why? In the first year, you will make a lot of mistakes. It could be naming conventions, architecting the whole system, or creating a contribution model. A lot of stuff will happen, and it will be overwhelming. Having an app that removes the decision fatigue for building a custom CMS will give you more time to think about the important stuff. After you figure out what you need, invest in an advanced documentation site. But don't make it custom just because the internet says so.

When you want to update your design system

If you want to update your
design system

If you are a big corporation managing multi-level brands, you already have a design system in one form or another. If you plan to upgrade it, don't throw everything in the trash. Figure out what went well, what it lacks, and where you want to go. You can add the rest of the brands when you figure it out. Otherwise, everything will become chaotic, and the work will start duplicating.

If you are a big corporation managing multi-level brands, you already have a design system in one form or another. If you plan to upgrade it, don't throw everything in the trash. Figure out what went well, what it lacks, and where you want to go. You can add the rest of the brands when you figure it out. Otherwise, everything will become chaotic, and the work will start duplicating.

If you are a big corporation managing multi-level brands, you already have a design system in one form or another. If you plan to upgrade it, don't throw everything in the trash. Figure out what went well, what it lacks, and where you want to go. You can add the rest of the brands when you figure it out. Otherwise, everything will become chaotic, and the work will start duplicating.

When you need to follow legal rules

My advice changes a bit for companies with security issues (for example, banks). Banks can only afford to share some source files via third-party apps. So, their only options are to use Figma API and custom build.


Now, let's go through some documentation tools:

My advice changes a bit for companies with security issues (for example, banks). Banks can only afford to share some source files via third-party apps. So, their only options are to use Figma API and custom build.


Now, let's go through some documentation tools:

My advice changes a bit for companies with security issues (for example, banks). Banks can only afford to share some source files via third-party apps. So, their only options are to use Figma API and custom build.


Now, let's go through some documentation tools:

Tools

Basic

Notion, GitHub Pages, Airtable

Advanced

Zeroheight, Knapsack, Specify, Supernova, Backlight, Storybook

Zeroheight, Specify, Supernova,

Backlight

Custom

Build your own documentation site

Build your own

Basic

Airtable

When you don't have a fully-fledged design system yet, you can create a robust, automated table in Airtable with the list of design components with status for the platforms you serve.


Airtable is a spreadsheet-database hybrid. It provides a powerful API and built-in support for several popular apps. You can add triggers when a record is updated or created or when a record matches conditions.


🌈 If you want the Design Component Airtable template, click here.

Notion

Notion works fine if you want a simple version of the design system. It's impossible to connect Figma files or Storybook easily, but it can work well if you only want to describe components. You might use it as the learning phase to see what works best and then upgrade to another third-party app or even a custom one.


You can duplicate a template for Design system from Notion's page. Open it.

GitHub Pages

You can host GH Pages directly from your GitHub repository and just edit, push, and your changes are live. You may have to spend some time teaching designers how to use Github, but it is relatively easy. The downside is that this differs from using an editor, and you will have to add links manually or embed stuff from Storybook, Figma, etc.

"Off-the-shelf" solutions

Zeroheight

Zeroheight is a central hub for designers, engineers, and product and marketing teams, and their editor allows you to add or edit pages. Some predefined templates help set up the design documentation for the first time, like dos and don'ts, where to add Storybook links (for code), how to add Figma links, how to describe the component, etc. Once ready, you can publish the site and share it with others (internal or external).

Supernova

Supernova is a new player in the design systems field, but a very powerful one. They are focusing a lot on design tokens, and recently, they added themes too. At first glance, it might look like Zeroheight app; however, their no-code features help a lot when adding new sections. They also offer a built-in code editor that allows you to render live code examples directly in your documentation. 

Knapsack

Knapsack is another design system platform that unites code and design, so developers and designers can work together in real-time. You can host live-rendered components, use multiple editors, developer contribution tools, and even prototypes.

Specify

Specify is a design API connecting all the tools within organization’s design system. It allows you to collect, store, and distribute design tokens and assets—automatically. You can get automatic Pull Requests for every design update on your GitHub repository. They currently support Figma and provide a GitHub app, an API, and a CLI to match the developer's needs.

Backlight.dev

Backlight combines design tokens, components, stories, and tests. To add the content, they've built embedded components and playgrounds. It's compatible with most frameworks. You can review visual pull requests and embed designs (Figma, Adobe XD, ...) or components via links. It's possible to manage versioning on repositories.

Storybook

Storybook is a tool for building and testing user interface components in isolation. It allows developers to create a library of components that can be used throughout an application and provides a way to preview and interact with those components live. It helps to ensure that each component works correctly and that changes to one component don't break other application parts. However, if we want to make a design system accessible to everyone and add written guidelines, the StoryBook itself is not enough. We will have to embed "stories" in another tool, such as Zeroheight.


I don't want to pick the best one since your team has specific needs. What will bring you closer to having a design system widely adopted?

I don't want to pick the best one since your team has specific needs. Only you know what will bring you closer to having a design system widely adopted?


I don't want to pick the best one since your team has specific needs. What will bring you closer to having a design system widely adopted?

Custom solutions

When building a custom design system, the sky is the limit. There are thousands of combinations that you can connect to get what you have in mind.

The easiest way is to use Figma for design and then connect their API to your tech stack. If you use Sketch or Adobe XD, I suggest migrating to Figma and starting from there. If, for some reason, your company is not allowed to use Figma, you will have more manual work, but the goal is still reachable.

When building a custom design system, the sky is the limit. There are thousands of combinations that you can connect to get what you have in mind.

The easiest way is to use Figma for design and then connect their API to your tech stack. If you use Sketch or Adobe XD, I suggest migrating to Figma and starting from there. If, for some reason, your company is not allowed to use Figma, you will have more manual work, but the goal is still reachable.

When building a custom design system, the sky is the limit. There are thousands of combinations that you can connect to get what you have in mind.

The easiest way is to use Figma for design and then connect their API to your tech stack. If you use Sketch or Adobe XD, I suggest migrating to Figma and starting from there. If, for some reason, your company is not allowed to use Figma, you will have more manual work, but the goal is still reachable.

Figma API

Figma offers Plugin API, Widget API, and REST API. There are many options to automate tasks, add functionalities and improve your workflow. You will move mountains by using Figma API and your custom code for the documentation site. And piles of money, too. (Yep, it takes time and team effort).

Sketch API

If you are not using Figma, Sketch also offers API, so you can connect it to your tech stack.

Vercel

Vercel is another platform that helps people build, host, and deploy websites and web applications.

Netlify

You can use Netlify and combine tools and APIs manually. You have all the freedom to build the custom documentation site, but be careful when making the documentation for the first time because you can quickly come to analysis paralysis and spend a lot of resources, even for no-brainer stuff.

Last tips

Make it logical 

Organize, baby, organize.

One search per day makes

the stress go away.

Before you start uploading your stuff and code, think about the structure and the language. Make it predictable and discoverable. Make sure everyone understand what you are writing about.

Do it iteratively.

Step by step.

One search per day makes

the stress go away.

Try out different approaches, put it in the wild, collect feedback and adapt quickly. Feedback loop is important, since organization's needs will change and grow over time.

Make it relevant 

An outdated design system is like no design system.

One search per day makes

the stress go away.

Write instructions in human language.

Make it searchable 

Powerful search per day makes
the stress go away.

One search per day makes

the stress go away.

Save the user's time and make it easy to skim through the docs.

What to put in?

Components

Add details of where, when, and why to choose it. Explain how the component can be combined with others to make the user flow as smooth as possible. Add details, such as:


  • Brief explanation

  • Explain where it lives in the user flow

  • Add live examples 

  • Include code snippets

  • Include Figma links (embeds)

  • Include examples

  • Include DO's and DON'Ts

  • Add combinations with other components

  • Add specific rules 

  • Add the status of the component

  • Add responsible person

Add details of where, when, and why to choose it. Explain how the component can be combined with others to make the user flow as smooth as possible. Add details, such as:


  • Brief explanation

  • Explain where it lives in the user flow

  • Add live examples 

  • Include code snippets

  • Include Figma links (embeds)

  • Include examples

  • Include DO's and DON'Ts

  • Add combinations with other components

  • Add specific rules 

  • Add the status of the component

  • Add responsible person

Add details of where, when, and why to choose it. Explain how the component can be combined with others to make the user flow as smooth as possible. Add details, such as:


  • Brief explanation

  • Explain where it lives in the user flow

  • Add live examples 

  • Include code snippets

  • Include Figma links (embeds)

  • Include examples

  • Include DO's and DON'Ts

  • Add combinations with other components

  • Add specific rules 

  • Add the status of the component

  • Add responsible person

Documentation structure

Getting started

Introduction
About
Contributions

What’s new?

Changelog
Monthly updates
Roadmap
Dependencies
Component status

Brand

Logo versions
Who we are
Typography
Strategy
Design Principles
Illustrations
Presentations
Motion
Colors
Tone of Voice

Design Tokens

Background colors
Border Color
Border Radius
Box Shadow
Duration/Transition
Elevation
Font Size
Font Weight
Font Family
Grid
Line Height
Responsiveness
Shadows
Size
Space
Transition
Z-index

Components

Avatar
Activation cards
Badge
Box
Buttons
Callout
Card
Checkbox
Code snippet
Column
Date picker
Dropdown

What’s new?

File uploader
Form
Link
List
Loading
Notification
Pagination
Popover
Search
Tab
Tooltip
etc.

Categories

Accessibility
Color palette and examples
Component overview
Iconography
Grid
Figma Toolkit (plugins, etc.)
Localization rules and tools
Layouts
Screen Sizes (rules)

Marketing

App store screens
Emails
Social media
Ads templates
Billboard templates
Print templates

Categories

Accessibility
Color palette and examples
Component overview
Iconography
Grid
Figma Toolkit (plugins, etc.)
Localization rules and tools
Layouts
Screen Sizes (rules)

Marketing

App store screens
Emails
Social media
Ads templates
Billboard templates
Print templates

GOODIES

GOODIES

GOODIES

Design Documentation Template

Design Documentation Template

Design Documentation Template

Simplify your handoff with this useful documentation template. You can easily customize all the styles and adapt them to your needs. Yay. 🌈

Simplify your handoff with this useful documentation template. You can easily customize all the styles and adapt them to your needs. Yay. 🌈

Simplify your handoff with this useful documentation template. You can easily customize all the styles and adapt them to your needs. Yay. 🌈

Previous

Next

Start reading

The Design System Guide

Chapters

Blog

Resources

Bookmarks

Design System Metrics

The Design System Playbook

Wall of Kindness

About me

My personal website

Twitter (X)

Linkedin

Newsletter

Writing on topics such as design systems,

design process, design strategy. ✨

© 2022 - 2023 The Design System Guide by Romina Kavcic

The Design System Guide

Chapters

Blog

Resources

Bookmarks

Design System Metrics

The Design System Playbook

Wall of Kindness

About me

My personal website

Twitter (X)

Linkedin

Newsletter

Writing on topics such as design systems,

design process, design strategy. ✨

© 2022 - 2023 The Design System Guide by Romina Kavcic

Start reading

The Design System Guide

Chapters

Blog

Resources

Bookmarks

Design System Metrics

The Design System Playbook

Wall of Kindness

About me

My personal website

Twitter (X)

Linkedin

Newsletter

Writing on topics such as design systems,

design process, design strategy. ✨

© 2022 - 2023 The Design System Guide by Romina Kavcic