Brought to you by zeroheight

How we document

2nd edition

Brought to you by

download the full report

Last fall, we launched the 2nd edition of our How We Document survey! It captures the current state of design system documentation as reported by the community. Over 500 people shared how things were going. We analyzed all the responses and gathered as many helpful insights as possible. We're excited to share with you the How We Document 2023 report. Use it to see if you're on the right track, set team goals, make business cases for more resources, and more.

Here are a few of the report highlights:

518 total respondents

design system experience

Most of our respondents have been working on design systems between 1-3 years (44%). As a large amount of people have under 3 years experience, this is an indicator that more people are beginning to include design systems in their work.

1. 0-1 years 15%
2. 44%1 - 3 years
3. 3-5 years 26%
4. 5-10 years 12%
5. 10+ years 4%

Graph showing length of time respondents have been working on design systems

Design system teams go beyond designers and developers

Design system teams don't just include designers and developers. Regardless of a design system's age, on average, there's at least one PM and one content writer on the team. It seems people are finally recognizing the importance of coordinating the team and writing good documentation. Older design systems have larger teams, which have scaled the number of people across the roles. Overall it's a healthy sign to see the investment of positions in a design system as time progresses.

1. 101032 8
   years
2. 4611 5-7
   years
3. 4511 2-4
   years
4. 3311 0-1
   years

• designers
• engineers
• content

Graph showing the different roles that make up respondents teams

Happiness and documentation maturity

Most respondents (34%) noted their design system documentation was partially mature (i.e., partial content, some dev integration). About a fifth felt their documentation was mature. When comparing maturity with documentation happiness, we’re not surprised with our findings. Those with very mature or mature documentation were overwhelmingly happy (82%). Documentation that wasn’t very mature had significant unhappiness (70%).

1. very mature 2%
2. mature 17%
3. 34% partially mature
4. slightly 26%
5. not very 21%

Graph showing how mature respondents design system documentation is.

5-7 tokens is the sweet spot for a design system

Defining six types of tokens seems to be the popular choice (31%) and the most popular (26%) token combination included: borders, colors, radius, shadows, spacing, and typography. Most respondents (59%) use between 5-7 tokens. Not many just dabble with a few tokens or go all in with over 8 tokens.

1. 1 token
2. 2 tokens
3. 3 tokens
4. 4 tokens
5. 5 tokens
6. 6 tokens
7. 7 tokens
8. 8 tokens
9. 9 tokens

list showing how many design tokens respondents use.

Documentation is great for truth, onboarding and confidence

We added this question this year to get a sense of people’s sentiment. Respondents feel that their current documentation serves as a single-source of truth (62%), helps with onboarding (61%), and informs teammates so they can do their job (53%) confidently. They feel differently about using it as a recruiting tool, where most are neutral (30%) or disagree (41%). The data made sense when we reviewed the comments. Mostly unhappy or mostly happy people feel their design system is still a work in progress and can improve.

• Serves as a single source of truth
  62%18%18%2%
• Helps onboard new employees
  61%17%18%4%
• Makes people who use it feel informed and confident in their job
  53%29%15%3%
• Helps us recruit employees
  14%30%30%15%

• agree
• neutral
• disagree

Graph showing how respondents feel about their current design system and how it serves them.

Over the next few weeks, we're also hosting a series of webinars diving deeper into the findings. Download the full report to see all the insights from the community. We'll also notify you when the webinars are open for registration.

download the full report