Documenting design is hard. Every design system team struggles with it. The creative designers who work magic in Figma often have a hard time writing about their creations — and how fellow designers can use them. And if the team is lucky enough to have a content designer, they can get swamped by the numerous details they need to spell out. How to structure and streamline writing about design? That was the goal of the component outline I’ll share in this article.
With design systems teams at Compass, Blue Shield of California, and others, I’ve developed and tested a spreadsheet tool for writing about components — one of the core elements of most design systems. This approach informs how we write documentation for the Teradata Covalent Design System. When I shared the outline with some team members working on the Condé Nast design system, they said, “This is like Mad Libs for design systems.” Exactly. We just write all the content down the list, and when we’re done, Voila! Documentation.
It’s not magic, but it can help you and your team write about your designs. Guiding people to build digital experiences efficiently and consistently is the goal of most design systems. Using the spreadsheet tool outlined in this article, we can enhance efficiency and consistency in documenting the design system itself.
Systems, people, and words
Design systems are collections of components, patterns, and guidelines for how an organization builds products and other experiences. Content is design, so content designers and strategists play a critical role (actually, a number of roles) in making systems understandable and useful. In “Content in, of, and for Design Systems,” Content Designer Michael Lawrence writes about how content can contribute to a system. One of those key deliverables is documentation about components.
We often think of components as the building blocks of design systems. Things like headers, buttons, navigation, and form elements like information entry fields or dropdown selection lists. Content appears in all those things, so content designers need guidelines for writing those words, our design partners need guidelines for how those words appear, and the engineering heroes who actually code the thing need to know just enough about all of the above to help bring it to life. That’s why designers — visual and content — and engineers must work together on a design system.
With a focus on both documentation and design, the content person can bring it all together and make sure the design system helps all the people who need to use it. Component documentation is a good example of this, as we need to write down and share information about visual design, content design, interaction design, accessibility, platform considerations (Android vs. iOS), and a lot more details. Let’s dig into those details.
Get more valuable content design articles like this one delivered right to your inbox.
Information, architecture, and design
In a design systems initiative for the real-estate company Compass, even before we started documenting our components, we wanted to take a structured, methodical approach to how we write about them. We wrote down all the details we might possibly document. We came up with a list of about 40 things — a potentially scary number of data points, but we began to organize and prioritize them. Yep, this was the fun information architecture part. Our thinking: if we had a component that required all 40 of those data points, how would we place the most important ones where they’d most likely be found and used?
We shuffled information around. We played with how our tools could help us organize the content (we were using Figma, zeroheight, and Storybook). We collaborated with design partners to do card sorting exercises with users to learn how familiar they were with design system terms and how they might want those terms to appear.
That content strategy and research led to this approach. It’s in a spreadsheet. It’s not pretty. But it’s useful. It helped us work with designers to craft attractive, navigable screens that can present the necessary information.
At Compass, we used this outline to document the 25 components in the system quickly. With a team of two dedicated content designers and collaboration with an engaged group of designers and engineers, the site launched three months earlier than management had expected. We had leadership and project management support, and this approach helped the team coordinate work and move fast.
A shock to the system
A warning: Once you list everything that can go into a component detail page, you might encounter some content shock. That occurs when team members (usually not content people) say something like, “That’s too much. We’re going to have to cut content.”
This moment of shock might come after you’ve finished writing and designing the complete component documentation. Someone will look at the finished work and realize (gasp!) that they have to scroll.
Systems documentation generally has to include all the essential things; it’s our job to organize the content and make it as findable and useful as possible. We need to remind our shocked partners about this and show them how we work to make sure the documentation is findable, correct, complete, and usable. Yes, it’s information architecture, and every design system needs a healthy dose of it.
Now it’s your turn
.png)
Download the component outline and try it out for your designs:
We expect that there will be some things you’ll need to adapt for your users and your brand. There might be missing data points, such as documentation about design tokens, variations for certain brand or product experiences, or how AI agents and related dynamic content might appear in the component. Feel free to adapt this tool to the needs of your system and your users. For example, the spreadsheet specifies this order of content at the top of the page:
- Breadcrumb navigation
- Title (component name)
- Brief description
The smart content design team at Blue Shield of California revised this approach:
- Breadcrumb navigation
- Title (component name)
- When to use [component name]
In the Blue Shield of California Cerulean Design System, the description is less important than quickly guiding designers to understand the use cases the component is for. The description seemed unnecessary for this team, as Figma files and visual design already described the component enough for their needs. The team opted to elevate the content that matters most to their users.
The outline in action
When I presented the component outline in workshops at Button in 2023, conference attendees asked great questions and gave me the idea to add Column C, where we can enter draft copy. This revision helps content designers see how to use this structure more clearly. And I’m sure content designers will find additional ways to customize this approach for their organization’s unique requirements.
If you’re using a structured approach to system content, you might follow this outline to break up documentation into reusable chunks. Then, design system content such as usability (“When to use [component name]”) and accessibility guidelines can appear where users need them, right in the tools they’re using (zeroheight, Knapsack, Figma, Storybook, etc.). This takes some planning and content engineering, but it’s well within the possibility of what our tools can support.
We might also be able to tap into this structure to draft a reusable prompt for generative AI tools. We could ask ChatGPT, Gemini, or whatever Gen AI tool we like to “write design system documentation for buttons, and include a title about buttons, a brief description of buttons, usage guidelines for buttons, an anatomy image of buttons, a description of buttons anatomy, etc.” Many design systems sites are public, and the large language models seem to have consumed a lot of content from those sites. Of course, use AI with caution. That first draft probably won’t match your designs, your brand, your voice, and the countless other design considerations that you need to consider and document.
Something borrowed, something new
Outlines and templates are nothing new. You might recognize this approach from the inverted pyramid structure we learned about in journalism class. Put the lead, the most important thing, first, and the other details follow.
A kernel of inspiration for this spreadsheet approach appears in the second edition of Content Strategy for the Web by Kristina Halvorson and Melissa Rach. Page tables appear on page 157 of my digital version of the book. (This might be my favorite thing in the book!) With a tabular approach like this, we start to see ways of organizing and streamlining our work. These tables and other research into design systems and content modeling were bouncing around in my head as I worked on this documentation outline.
What might be most valuable here is the list of all the design-system-component content things. And the reminder to systematize content types we inevitably need to repeat. Help articles, getting started guides, component documentation, emails, and more — let’s organize them so we can write faster. Our creativity as writers can still shine in these structures. Just think of how many poets have succeeded within the strict boundaries of the sonnet. Invent the wheel once, my friends. Then roll with it.
