How We Document 2023 Report - Zeroheight
- 1. how we document 2023 brought to you by
- 2. welcome to 2023 Design system documentation continues to gain momentum every year. How We Document is an opportunity for us to reflect on the changes and challenges we face as a community. This year, over 500 of you participated to establish where we're at, where we're going, and where we need to be.
- 3. contents your design system and documentation your design system and happiness your design system team your organization who took this survey
- 4. who took this survey
- 5. 72% of disciplines were Design & UX 9% engineering 6% product management 7% design ops 3% content Design roles represented most of the respondents ( ). Engineering, DesignOps, and Product Management were relatively even. 72% primary discipline Respondents: 518
- 6. There were 238 unique job titles from our respondents. Interestingly enough, of the job titles explicitly state “design system.” This could be a strong indicator that the industry is recognizing the importance of design systems. 16% job titles 4% product manager 5% other 77% designer 10% engineer 2% design ops 2% content 69% of people have documentation as a core part of their role Respondents: 518
- 7. design system job titles We compiled a list of the unique job titles for design system people. If you’re looking for a new role or to expand your team, these are the titles organizations are using. Design System Product Lead Design System Lead Lead Designer, Design System Lead Product Designer & Design System Manager Lead Product Designer, Platform & Design System Visual Design Lead - Design System Design System Designer Senior Design System Designer Senior Product Designer, Design System Design Senior UX Designer, Design System Product Designer, Design System Management Design System & UI Manager Design System Community & Support Manager Senior Design System Manager Design System Product Strategy Manager Design System Manager Director Design Systems & Ops Head of Design System Senior Design System Ops Design Ops & Design System Manager Senior Program Manager, Design System Design System Manager / Ops Operations Product Manager, Design System Design System Product Manager Product management Design System Developer Engineering Design System Tech Lead Design System Engineer Senior Design System Engineer Principal Design System Engineer Design System Specialist Senior Design System Analyst Senior - Design System UX Writer Other roles
- 8. Most people who completed the survey have been working professionally for over 10 years. This can imply that design systems are not an inexperienced person’s game. However, this shouldn’t discourage entry- level professionals. There’s certainly room for less experienced professionals and teams are making space for them. professional experience 52% 10+ years 26% 5 - 10 years 11% 3 - 5 years 10% 1 - 3 years 1% 0 - 1 years Respondents: 518
- 9. design system experience 26% 3 - 5 years 15% 0 - 1 years 12% 5 - 10 years 4% 10+ years 44% 1 - 3 years Respondents: 518 Most of our respondents have been working on design systems between 1-3 years ( ). 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. 44%
- 10. more seasoned professionals work on design systems We added this new question this year. While most of the respondents are 25-34 years old, it was only slightly higher than the number of 35-44 year olds. We can see why this might be; design systems are usually complex in nature and require cross-functional coordination. More seasoned teammates typically handle projects like these. 42% 25 - 34 years old 55+ years old 45 - 54 years old 35 - 44 years old 18 - 24 years old 3% 15% 36% 3% Respondents: 518
- 11. age doesn’t equate to design system experience under 1 year 1 - 3 years 3 - 5 years 5 - 10 years 10+ years Respondents: 518 18 - 24 years 56% 31% 13% 35 - 44 years 34% 11% 33% 17% 5% 45 - 55 years 43% 11% 18% 11% 17% 25 - 34 years 16% 54% 5% 25% 55+ years 43% 22% 7% 14% 14% Regardless of age, most people only had 1-3 years of design system experience. Most people with 3-5 years of experience were 35 to 44-year-olds. One could guess the timing was right in their career. They likely had enough professional experience to explore design systems when it was new. What's encouraging is that regardless of age, most people are relatively new to design systems, so the playing field is pretty even.
- 12. women are well represented We asked about gender this year, to get a sense of the landscape. For our respondents, identified as male and identified as female. It’s great to see there was a good representation of women considering women only make up of the workforce in tech.* 54% 41% 26% 41% male 54% 2% female non-binary, genderqueer or gender non-conforming Respondents: 513 *According to the US Bureau of Labor Statistics https://www.bls.gov/cps/cpsaat11.htm
- 13. most roles are dominated by men Organizing roles by gender reveals that most roles are male dominated. The only role that was mostly women were content roles ( ). Design and UX roles were a little more balanced with identifying as men and identifying as women. Interestingly enough, of people that selected “other” as their discipline were women and only men. Based on written responses, most of these roles were hybrid in nature. 76% 51% 43% 50% 42% Content 76% 6% 18% women prefer not to say men Other 50% 42% women men 8% prefer not to say Design & UX 51% 43% 1% men women prefer not to say non-binary 4% DesignOps 68% 27% 3% men women prefer not to say non-binary 3% Engineering 80% 11% 2% men women prefer not to say non-binary 7% PM 56% 38% 3% 3% men women prefer not to say non-binary Respondents: 518
- 14. men only slightly outnumber women in some levels A majority of our participants were managers, individual contributors, and freelancers/ consultants. Men only led women by a little. We had fewer respondents at the exec and founder/ owner roles, which had more respondents identify as men. But there were more non-binary respondents than women for the founder/owner level. Executive 61% 32% 7% men women prefer not to say Founder/Owner 63% 13% 25% men women non-binary 2% Freelancer 2% non-binary 54% 40% 4% men women prefer not to say non-binary Individual Contributor 50% 43% 5% men women prefer not to say Manager 59% 36% 5% men women prefer not to say Respondents: 518
- 15. ethnic identity isn’t very diverse Respondents were overwhelmingly white or European. The percentage of all the other ethnicities combined were still less than those two combined. In terms of gender and ethnicity, most of our respondents identified as white or European men, followed by white or European women. This is a strong indicator that we all have work to do in increasing the diversity in this discipline. Having a diverse team provides more perspectives and brings about more ideas. What can we do to increase equity and representation in the discipline? Respondents: 503 32% white 30% european 6% 6% 4% 3% 2% 2% 2% 1% 1% 1% 1% asian hispanic, latinx south american north american multi-racial southeast asian indian african bi-racial middle eastern south asian 0.4% 0.4% 0.4% 0.4% 0.4% 0.2% 0.2% 2% 6% black central american east asian ethnoreligious group indigenous (e.g., native american, indigenous australian) caribbean north african other prefer not to say everyone else
- 17. how big is your organization? 37% 10% 500 - 999 people 23% 100 - 499 people 0 - 99 people 30% 1000+ people Most respondents worked at companies under 100 people ( ) followed by people working at larger, enterprise-sized companies ( ). 37% 30% Respondents: 518
- 18. in-house or agency Overwhelmingly, most respondents work in-house, as opposed to agency, or being self-employed. 85% in-house 9% agency 5% self-employed 1% other Respondents: 518
- 19. your design org Small design orgs, under 10 people, are in the majority. Respondents: 518 54% 1 - 10 people 18% 11 - 20 people 13% 21 - 50 people 7% 51 - 100 people 7% 101 - 1000 people 1%1000+ people
- 20. designers & engineers organization size there are this many engineers for every one designer 19 1000+ 10 100 - 499 13 500 - 999 7 50 - 99 4 0-49 When it comes to the designer to engineer ratio, the ratio grows with organization size. The increase is fairly steady, but jumps significantly with organizations over 1000 employees. Respondents: 518
- 21. your design system team
- 22. design system teams are more likely in bigger organizations It’s great to see that most companies ( ) have a design system team! Among those teams, roughly half have dedicated employees. The larger the company size, they more likely they'll have a team with dedicated employees. Most small organizations only have teams with employees partially resourced. 61% 61% have a team 31% have a team with full-time employees 30% have a team that's partially resourced 34% 4% other don’t have a team 1 unsure Respondents: 518
- 23. A majority of design system teams are between 4-9 people ( ). Breaking the 10+ group even further, we learned of teams have 20+ people. To see how many teams are on the larger size is a great sign for the discipline! 40% 8% design system team size Respondents: 152 40% 4 - 9 people 25% 1 - 3 people 35% 10+ people
- 24. As a company size increases, so does their design system team size. However, the size doesn’t scale at the same proportion. But to some extent, this makes sense. Design system teams are built with efficiency in mind, so there isn’t always a reason to scale the team proportionately. The average team size for companies under 10 employees is high. At this size, we suspect employees wear multiple hats and teams have an “all hands on deck” approach. design system team size increases with company size organization size average number of people in design systems team 10 - 49 0-10 50 - 99 500 - 999 1000+ 100 - 499 6 4 5 5 9 11 Respondents: 152
- 25. design system teams go beyond designers and developers designers number of people engineers PM content 3 3 1 1 0 - 1 years 4 5 1 1 2 - 4 years 6 4 1 1 5 - 7 years 10 10 3 2 8 years 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. Respondents: 518
- 26. your design system and documentation
- 27. Most of the design systems are 1 year old ( )! A majority of the design systems ( ) are under 3 years old. It’s safe to say, if you don’t have a design system yet, it’s not too late to start! 39% 82% design systems are gaining traction 8% 4 years old 17% 3 years old 26% 2 years old 39% 1 year old 10% 5+ years old Respondents: 518
- 28. documentation has become a natural part of the process 12% 19% 5% 5% 9% 3 years old 2 years old 4 years old 5 years old under 1 year old 49% 1 year old Eighty-nine percent ( ) of design system docs are between 0-3 years old. The difference between starting your design system and documenting it is relatively low. This year, of design systems start documenting within 1 year of starting their system. This is a good indicator that documentation is becoming seen as part of the design system process. 89% 87% Respondents: 518
- 29. code and code-first tools are leading the charge notetaking tools 3rd party DSMs self-built solution design tool itself 69% code and code-first tools 54% 35% 47% 15% Like last year, most respondents spread their documentation across many tools. This year, code and code-first tools are the most popular now. This could mean those tools are becoming more robust for design systems. Respondents: 518; allowed to select multiple
- 30. the most popular documentation tools Respondents: 518; allowed to select multiple The design tool itself 54% Storybook 47% Google Docs 6% Self-built solution 15% Confluence 21% zeroheight 41% Notion 9% ReadMe 3% GitHub Pages 7% In-code documentation 10%
- 31. Like last year, organizations continue to use a combination of tools to get the job done. Our top combination this year is zeroheight and Storybook ( ). Teams also rely on just their design tool and Storybook ( ). Even though not a specific design system documentation tool, Confluence is in combinations that round out the top 5. While most people said they have separate design and developer documentation ( ), it’s only higher than those who don’t. It’ll be interesting to see if this gap narrows next year, since it could be an indication that we’re reaching that single source of truth we’ve all be wanting. 13% 8% 54% 21% tool combination bingo Respondents: 518; allowed to select multiple 13% 3% 3% 6% 9%
- 32. Most respondents claimed that less than of their design system was documented ( ). On the other hand, also said their design system was at least covered. 25% 36% 36% 75% very few have their systems 100% documented 29% 28% about 50% about 75% 100% 36% under 25% of the design system is documented 7% Respondents: 518
- 33. UX research 10% motion guidelines 16% sound guidelines 3% grids 52% spacing 53% design tokens 48% forms 57% atomic components 79% color 85% typography 74% code for components 47% brand guidelines 58% illustration guidelines 23% accessibility guidelines 38% example page 27% code usage guidelines 26% contribution model 16% what does your documentation include? principles 46% layout 42% complex components 42% voice & tone 30% release notes or change log 29% UX copy guidelines 26% Respondents: 518; allowed to select multiple
- 34. most of our documentation is monolingual Few teams localize their systems ( ). A majority of respondents said their design system documentation is not localized. When cross-referencing our data, we didn’t see any correlation between localization and maturity or organization size. 10% 80% do not localize 11% 10% unsure do localize Respondents: 518
- 35. version control is a sign of maturity Most of the respondents don’t use any versioning or releases in their documentation ( ). About a third ( ) use releases and about a quarter ( ) intend to include this in their documentation. The more mature the design system documentation is, the more likely it is to have versioning or releases. Of very mature docs, 82% have versioning and releases. Of mature docs, about half ( ) have it, and of partially mature docs, have it. 42% 28% 26% 47% 34% 28% has version control 4% unsure 25% do not, but is in progress 42% do not have version control Respondents: 518
- 36. we have one, but contributions are low how people contribute to your design system 33% starting to create one 26% we don’t have one 7% we have an effective contribution model 5% unsure About a third of respondents ( ) have a contribution model and about a third are creating one. Of those that have a contribution model, very few ( ) have a model they feel is effective. We compared these contribution responses by the average number of contributors. Larger teams (8-10 people) are either creating a contribution model or don’t have one at all. Teams with an effective contribution model have an average of 3 contributors. As a team scales, they need a contribution model, but are models effective only because there are fewer contributors? 36% 20% Respondents: 518 16% 13% we have one, but it isn’t widely understood
- 37. Designers are the people who most contribute to documentation ( ). With content people at , this could imply that organizations are taking documentation seriously and ensuring that there’s a good experience with it. When looking at things a little deeper, the distribution of who documents is relatively even across org size. Larger organizations usually have more content people contributing to documentation. 88% 18% who documents your system? 88% 41% 18% 3% 3% 3% engineers content strategist, UX writers, content designers marketing documentation specialists other designers Respondents: 518; allowed to select multiple 13% product managers
- 38. This year, only have a governance process. Most respondents ( ) are working on creating process now. We’re not surprised since many respondents said their design systems just were a year old ( ). As you can imagine, getting a design system up and running has to happen before teams can establish a governance process for documentation. 40% 29% 39% governance isn't as common not yet but working on it 29% yes, with an informal process 27% no, we don’t review changes 26% yes, with a formal process 13% unsure 4% Respondents: 518
- 39. About half of respondents say they don’t have content guidelines for document creation. Very few ( ) have them in place, however about a third are in the process of adding them. But with a large number of design systems under a year old ( ), content guidelines might not be needed just yet. 18% 39% not many have content guidelines for their documentation no 47% not yet, this is in progress yes unsure 32% 18% 3% Respondents: 518
- 40. measuring the success of your documentation Only of respondents track metrics on their documentation. However, of respondents are working toward measuring. Even if not tracking metrics, more of respondents ( ) have Key Performance Indicators (KPIs) directly associated with the success of their documentation. 10% 17% 16% 70% don’t track metrics on their docs 77% don’t have KPIs for their docs Respondents: 518
- 41. Out of those who have KPIs, adoption was ranked the highest. This year, we added product consistency, speed of design delivery, and speed of development as options and they all ranked high. Net Promoter Score (NPS) as a KPI ranked the lowest. adoption is the key concern 54% speed of development 53% team productivity 48% documentation coverage 37% team happiness 7% other Respondents: 120; allowed to select multiple 18% viewer growth 18% NPS 52% speed of design delivery 59% product consistency 68% design system adoption
- 43. Defining six types of tokens seems to be the popular choice ( ) and the most popular ( ) token combination included: borders, colors, radius, shadows, spacing, and typography. Most respondents ( ) use between between 5 -7 tokens. Not many just dabble with a few tokens or go all in with over 8 tokens. 31% 26% 59% defining 5-7 tokens is the sweet spot for a design system 31% 6 tokens 15% 5 tokens 13% 7 tokens 11% 4 tokens 10% 3 tokens 7% 2 tokens 6% 1 token 5% 8 tokens 2% 9 tokens Respondents: 266; allowed to select multiple
- 44. A majority of token definition is still done primarily in design tools and code. More definition is happening in design tools ( ). There’s less happening in code ( ) and in token management platforms ( ). Last year, we wondered if this would be there case since design tools were building this into their products or had plug-ins (e.g., Tokens Studio for Figma). It looks like it’s making an impact. 77% 45% 12% but where are tokens defined? 77% design tools 45% code 12% token managment platform 5% other Respondents: 266; allowed to select multiple
- 45. design tokens and continuous integration It’s about even for those who have continuous integration with tokens and those who don’t have it ( each). However, about the same amount ( ) are trying to figure this out for their system. From this, it can seem like the field is still trying to navigate this area. 31% 27% no 31%not yet, but trying 27% unsure 11% yes, from design to code 21% yes, syncs both ways 6% yes, from code to design 4% Respondents: 266
- 46. what are the hallmarks of mature design system documentation? 100 - 499 26% 0 - 99 28% 1000+ 500 - 999 This year, mid-size companies have more mature systems than mid-large size companies. This tells us smaller companies might be a little more nimble in getting their system to a mature state. 36% each Respondents: 518
- 47. what are the hallmarks of mature design system documentation? 51% have version control, compared to as the average 28% 75% have dedicated design system teams, compared to as the average 61% 61% have a contribution model, compared to as the average 54% 65% use design tokens, compared to as the average 51% The gap between the hallmarks of a design system are narrowing. This could mean that it’s much easier to get your design system up to speed and there’s more investment focused on them. Respondents: 518
- 49. documentation is great for truth, onboarding and confidence 54% 62% 18% 18% 2% Serves as a single source of truth 61% 17% 18% 4% Helps onboard new employees 53% 29% 15% 3% Makes people who use it feel informed and confident in their job 14% 30% 30% 15% helps us recruit employees 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 ( ), helps with onboarding ( ), and informs teammates so they can do their job ( ) confidently. They feel differently about using it as a recruiting tool, where most are neutral ( ) or disagree ( ). 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. 62% 61% 53% 30% 41% Respondents: 516 n/a neutral disagree agree
- 50. your design system and happiness
- 51. design systems teams need a hug 31% 26% 3% 10% Overall happiness with their documentation is split across respondents. The “mostly happy” and “neither happy nor unhappy” sentiments were tied at . Following that, said they were “mostly unhappy” . Only reported they were “very happy” and were “very unhappy” . In the next few pages, we’ll dive into the hallmarks of those who are happy with their documentation. 31% 26% 3% 10% Respondents: 518 each
- 53. happiness with the design system documentation and their role Depending on their role, people are feeling less happy and more neutral. While managers are the happiest ( ), individual contributors (IC) are feeling more neutral ( ), and freelancers or consultants are feeling mostly neutral ( ). In some ways this makes sense, when digging through comments, managers are happy with their team’s work so far. From an IC perspective, even though they’re making good progress, they know there’s always more work to be done. 40% 38% 42% 34% individual contributor 14% executive 25% founder or owner 25% freelancer or consultant 40% manager Respondents: 518 % of happy respondents
- 54. Agency people are the happiest bunch ( ). In-house people are the least happiest ( ). The happiness sentiment was evenly distributed between happy, unhappy, and neutral for in-house folks. Looking into comments from in-house people, they’re happy because the design system provides value, even though they know there’s still work to be done. Neutral sentiments were attributed to their systems being a work in progress and the lack of resources. Unhappy sentiments included process challenges, outdated information, difficulty to maintain, and lack of resources. 43% 20% is happiness related to being in-house? 43% agency 33% self-employed 20% in-house Respondents: 518 % of happy respondents
- 55. People with full-time dedicated teams indicate slightly more happiness ( ) compared to those with partially-resourced teams ( ). While we can assume most people would love a dedicated team, organizations might be happy with the resources they have. Those without a design system team report only happiness. Overall when it comes to happiness, it seems that even having a partially resourced team is better than no team at all. 40% 36% 27% happiness in your design system team yes, with dedicated full-time employees 40% yes, partially- resourced employees 36% no 27% Respondents: 518 % of happy respondents
- 56. how much is covered in a happy design system? When more of the system is documented, people are happier. Our survey indicates that of happy people had at least of their design system documented. On the contrary, only of people were happy when of their design system was documented. 60% 75% 12% 25% 60% at least 75% is documented about half 28% about 25% 12% Respondents: 518 % of happy respondents
- 57. happiness in contribution we have an effective contribution 59% we have one, but contributions are low 47% we have one, but it isn’t widely understood 31% we’re starting to create one 28% we don’t have one 23% When it comes to contribution models, having a functional model correlates to happiness with your documentation. Happiness seems to be more about having your contribution model understood and less about having active contributions. Teams who are starting to create a contribution model seem to be more unhappy with their documentation ( ). It’d be interesting to see if their happiness is a correlation of not having a contribution process or if their unhappiness is impetus for creating a contribution model. 43% Respondents: 518 % of happy respondents
- 58. happiness in contribution governance yes, there’s a formal review process 55% yes, an informal process 46% no, we don’t review changes 24% not yet, but working on it 21% People are more happy with some sort of governance model for documentation. Respondents: 518 % of happy respondents
- 59. happiness in design system governance model Happiness seems to strongly correlate to having a centralized or hybrid governance model in place. Only of those who have a federated governance model reported happiness. We can see how this might be - centralized and hybrid teams typically have resources and accountability with maintaining documentation. When teams are federated, they’re often running a little more scrappy and might not have time to maintain documentation. 24% 39% 24% federated hybrid centralized Respondents: 518 each % of happy respondents
- 60. more time leads to more happiness This isn’t surprising that when people are able to spend more time on documentation, they’re happier with it. People who spend 1-3 days a week or most of their week are the happiest. Respondents who spend less than an hour or up to a day per week are the least happiest. 1 - 3 days per week 46% 19% 34% neutral unhappy happy up to a day a week 38% 22% 41% documenting is the majority of my week 55% 18% 27% 2% less than an hour a week 41% 33% 26% Respondents: 518
- 61. peopleusingthird-partyDSMsare happier Happinessisrelativelyevenacrosstoolsusedfor documentation,butpeopleusingthird-partyDSMsarethemost happy( )andleastunhappy( ).Peopleusingthedesigntool itselforself-builtsolutionsseemtobeinalove-haterelationship withtheirtool(eachwith forhappinessandunhappiness). 42% 25% 38% 3rdpartyDSMs 42% selfbuilt 38% thedesigntoolitself 38% note-takingtools 28% Respondents:518;allowedtoselectmultipletools %ofhappyrespondents
- 62. That’s a wrap for the How We Document 2023 report! Thanks for participating and checking it out. Over the next few weeks, we’ll be hosting a series of webinars that dive deeper into some of the findings. Sign up on our mailing list to be notified. We’ll be back at the end of the year to see how things have evolved over the next 12 months. Will we have more documented? Will teams get even bigger? Will we move the needle on building more inclusive teams? thanks, everyone!
- 63. try out zeroheight today This report was brought to you by zeroheight, the design system documentation platform that helps you build design systems everyone loves to use. We conducted the survey from Sep to Nov 2022 across social media, industry Slack channels, conferences, and emails to design system professionals. Use code HWD23 to receive 30-day free trial of our Starter Plan. brought to you by