.jpg)
TL;DR
- Documentation is a necessary part of building design systems that work, but it’s often tedious to write and not everyone is familiar or comfortable with doing so.
- By leveraging the power of AI we were able to speed up the documentation process and put a system in place that anyone can follow.
Thorough documentation is key to the success of any design system, but let’s be honest—it can be a bit of a headache to create. This is especially true when you’re short on time, or if authoring design system documentation isn't something you’re familiar with.
I recently spent several months building out a complex design system for one of our clients. For this project, we were responsible for the design, and the client’s development team would use the system to build out new pages. To ensure consistency during implementation, the documentation for the system had to not only be thorough but also easy enough for anyone on their team to follow. We wanted to be as efficient as possible, and set out to see how AI tools could help streamline and systematize the process.
In this post, I’ll walk you through how I used AI to generate and refine documentation for over 100 components in a fraction of the time it would have taken to write it all from scratch.
Let’s dive in.
Step 1
Open a new chat in your favorite AI platform. I used ChatGPT by OpenAI, but you could probably get similar results from Claude by Anthropic, Gemini by Google, or any of the others. I personally found ChatGPT’s responses to be the best balance of informative and streamlined, but each platform has its own strengths and weaknesses that you might want to test to find the output that works best for you.
Step 2
Copy/paste the prompt below as your first message. This prompt provides some initial context and instructions that will inform the process and format of the output, and avoids having to re-input the same information over and over.
This prompt was crafted to align with the specific needs of the design system I was building, and may vary from the exact information you need. I recommend viewing this as a starting point, and adapting the prompt as necessary to get exactly the output you’re looking for.
Example prompt to copy/paste:
I need you to help me create design system documentation pages for components in our design system. The audience for this documentation includes designers, developers, and content designers who may be new to the company, have entry-level experience, or are seasoned professionals. The content should be written in a professional yet casual tone, from the perspective of a senior-level design system designer, using plain language and concise bulleted lists rather than paragraphs. Please indicate where images could be helpful, especially for do/don’t pairs.
I will provide the following format for the component details:
Component Name: NAME
Component Variants: VARIANTS
Component Use-Case: USE-CASE
I need the documentation to follow this structure:
H1: Component Name
H2: Overview
Provide 1-3 sentences about what this component is used for, what it displays, and how users interact with it.
H2: Usage
General guidelines for designers and developers. Examples of proper use and misuse. Summarize any do/don’t usage pairs and indicate where images could illustrate key points.
H3: When to Use
Provide examples of when this component might be used.
H3: When Not to Use
Provide examples of when this component should not be used. Indicate whether another component might be more appropriate.
H2: Variants
Define and explain when to use each variant (if applicable).
H2: Behaviors
Describe how the component behaves with user/system interaction. Cover state changes (e.g., hover, active, disabled). Note any additional behaviors developers should consider.
H2: Accessibility
Explain design system responsibilities for accessibility. Provide considerations for both developers and designers.
H2: Content Guidelines
Guidelines for text elements, including max character counts, ideal copy length, and recommended tone. Summarize do/don’t examples and suggest image ideas.
H2: TL;DR
H3: Best Practices
2-3 key bullets that summarize usage best practices.
H3: Content Notes
2-3 bullets that summarize content guidelines.
ChatGPT should respond with a generic affirmation like: “Got it! Provide the component details when you’re ready and I'll create the documentation.”
Step 3
Now for the fun part. For each component, provide individual info in the format below. Just copy/paste and provide the name of the component, a list of variants (if applicable), and a brief one-sentence description of what the component does.
Component info to copy/paste:
Component Name: NAME
Component Variants: VARIANTS
Component Use-Case: USE-CASE
For example, to document an Accordion component I input the following:
If your AI tool allows image uploads, you could attach an image of the component in this request to provide additional context, which was sometimes helpful. Though more often than not it seemed to get too caught up on specific text in the image rather than seeing the bigger picture.
After a few seconds you’ll have a formatted documentation response with all the requested info. How does it look?
Below is part of the response I got for the Accordion. Even if we use the same prompt, each output will be different, so yours will likely have nuanced differences compared to mine. If you’re not satisfied with the output you can always hit “try again” to generate a new response.
Step 4
Make any necessary tweaks or adjustments. The AI tool doesn’t have all the same insight or context that you do and it might get some things wrong for your specific design system. You can either edit the output yourself, or simply respond and outline the changes you want ChatGPT to make for you.
Step 5
In the same chat, repeat steps 3 and 4 for each component in your system. This running chat not only acts as a single source you can go back to, but it also allows ChatGPT to have the full context of the design system and learn from itself.
Final Thoughts
An important thing to keep in mind is that while AI can provide a solid foundation or starting point, it’s not perfect.
You’ll still need to comb through the output to review and tweak, and add in documentation around unique details like character limits, component properties, or other specifics that AI just isn’t aware of.
AI also did a better job documenting common components that are part of essentially every design system, such as buttons, accordions, cards, etc. Basically everything on the Design System Checklist. It had a bit more difficulty grasping unique components that are not part of every system, and I had to guide it with a few more specific details to get the output I needed.
But even with this little bit of extra work, using AI for design system documentation is an invaluable way to get the ball rolling and is significantly quicker and easier than writing it all yourself.
Now you can spend more time on the important things—like complaining about Figma’s UI changes.
.png)
.png)