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 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.

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

Don't write poetry. Don't use jargon and fancy words.

Write how you've done it in simple language, explain where to use it, and add guidance for using it again.

Be as straightforward as possible. Don't write essays; no one will read them.

People using the design system will only use the components when they fully understand the specifics.

Don't write poetry. Don't use jargon and fancy words.

Write how you've done it in simple language, explain where to use it, and add guidance for using it again.

Be as straightforward as possible. Don't write essays; no one will read them.

People using the design system will only use the components when they fully understand the specifics.

Clear and thorough documentation is an essential part of any design system.

Clear and thorough documentation is an essential part of any design system.

The Impact of a UI Component

If you think little UI twikies don't affect anything, look at the diagram below.

If you think little UI twikies don't affect anything, look at the diagram below.

If you think little UI twikies don't affect anything, look at the diagram below.

How to choose the right tool for the documentation?

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?

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 include?

Each section should be easy to understand. Don't overcomplicate.

Each section should be easy to understand. Don't overcomplicate.

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

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. 🌈

About me

The Design System Guide Newsletter

Get new tips in your inbox every week about design systems & strategy.

© 2022 - 2024 The Design System Guide by Romina Kavcic

About me

The Design System Guide Newsletter

Get new tips in your inbox every week about design systems & strategy.

© 2022 - 2024 The Design System Guide by Romina Kavcic

About me

The Design System Guide Newsletter

Get new tips in your inbox every week about design systems & strategy.

© 2022 - 2024 The Design System Guide by Romina Kavcic