How to use ChatGPT when working on design systems documentation

Making a clear and understandable design system for everyone in the company can take time and effort.

I’m not just talking about creating and maintaining design system documentation; I’m talking about using it from the perspective of the design system user (designers, developers, product managers, etc.).

Often, writing the documentation is the easiest part of this process, but getting people to follow the instructions and use the documentation is the most challenging.

This article will explore what you can do with ChatGPT or another ai tool to create, maintain and consume design system documentation.

It is not necessary to be afraid of ChatGPT

The boom of ChatGPT and other generative AI tools is causing many people to become afraid of using these tools because they think the machines will replace them.

It is true for some tasks; for example, hiring a person today to translate CVs or simple websites is unnecessary because AI tools can do it. In addition, content marketing creation is so fast today that it can make marketing people afraid of losing their job position.

From my experience, I have been working and testing several tools since almost two years ago, including Wordtune, Rytr, Nichess, and others. These tools can only replace some of our tasks, and we must work with them to achieve clear results. We can use them to help us, but they cannot replace our criteria and decision-making.

For example, I can write in English even though it is not my native language because I trust the tools to correct my grammar errors. On the other hand, I cannot trust the machine to write the content since the AI cannot precisely say what I want, and human feedback is needed.

In other words, we should not be afraid of them but rather adapt them to our tasks so that they can assist us.

So don’t worry, the AI tools won’t replace you (maybe in the future), but they can increase your efficiency and accuracy.

Trusting AI 100% is not a good idea

AI is a great technology that can save you time and help you work more efficiently, but I am not recommending you trust 100% what it writes.

AI is still limited in its capabilities and can make mistakes. It is important to check and verify the results generated by AI. For example, AI-generated reports may lack accuracy due to limited access to data or incorrect assumptions. Due to this, it is imperative to double-check the results.

Writing design system documentation

Yes, it is possible to run a prompt and ask ChatGPT to generate a complete document for a component. I saw a test that Chris Lüders did. The results of ChatGPT he showed in this post are good because he created an excellent prompt.

Keep in mind that it can help you, but you’ve got to ensure the information is accurate and customize it to suit your system. For example, color and size are simple examples that you must review.

Although Chat GPT can’t give you a document that’s 100% perfect, it can generate a basic structure and save you a lot of time.

If you want to see another example of how ChatGPT generates documentation for a component, you can take a look here:

The Prompt
I am a designer that works in the design system team. I need to write documentation for a toggle component for the design system.

Here are the guidelines and main points to mention:

The document provides an overview of the toggle, including an explanation of its anatomy and a guide on how to use it.

The document also delves into the differences between the toggle and other common form elements, such as the checkbox, switch, and radio button.

In addition to the descriptive information, the document includes several tables. The tables include details on toggle sizes (M, L, XL), colors, design tokens, and different states.

Can you write the documentation for me?

Here is the response of chatGPT

Documenting design systems with ChatGPT.

Furthermore, ChatGPT can provide ideas on simplifying complex text so people can better understand it.

Here is the prompt:

Here is a text from a design system documentation. Can you write it simply so developers and designers will understand it easily?

As a user interface element, a toggle component is used to switch between two states, either “on” or “off.” By using the toggle component, users can quickly and conveniently change a setting from one state to the other.

Here is the response of chatGPT

With ChatGPT, you can simplify the text
With ChatGPT, you can simplify the text

In addition, if you have guidelines on how to write the design system document, you can include them in the prompt. For example, if the guidelines mention that the text should be as short as possible, you can include it in the prompt.

Here are two examples of prompts:

  1. Here is a text from a design system documentation. Can you write in the shortest way possible?
  2. Here is a text from a design system documentation. Can you write it in up to 35 words?

Write design tokens

Everyone who worked with the design systems knows that creating a clear design token system can be challenging.

Apart from organizing all the tokens, Writing all possibilities one by one can be a tedious task that can waste a lot of time. To avoid all the work, you can define the basic structure and all the variants and ask Chat GPT to write you all the possibilities.

Here is the prompt:

Please write all the combinations I can have for this token structure:


The variants are:

  • Theme: Dark, light
  • Component: checkbox
  • Size: Small, Medium, Large
  • State: Enable, Disable, Focus, Hover
  • Color: Background, Border

Here are all the possible combinations of the token structure:


It’s crazy how a tedious task that once took so much time now takes less than a minute with ChatGPT.

Check out my full article about design tokens and ChatGpPT here:

Find out what a component’s name is

Many times we need help with what name we should give a component. For example, a toggle can be referred to as a switch, toggle, or toggle switch.

It’s true that we have to read different design systems to understand how to call components. However, sometimes we have to figure out if there is a difference.

In that case, we can use chat GPT to explain things, for example:

Here is the prompt:

I am a designer that works in the design system team, and I do not know how to call the toggle component.

According to what I read, it could be called a toggle, switch, or toggle switch. Is there a difference between these names?

Here is the response of chatGPT

Let me be honest, I won’t take the answer as the truth, but I will consider it when making a decision.

Summarize the design system updates

When updating the library, not all designers read the updates from Figma, and this is because they are usually in the middle of their design process and do not take the time to read everything. In that case, writing a short Slack message will be more effective.

To work faster, you can create a prompt and run it every time you update the design system. It can be something like that.

👉 Note: This is not a real example, but I wanted to illustrate the technique. You can copy the prompt and try it for yourself if you like.

The prompt

We are a design system team, and we released four new updates to our design system. We want to send all 50 designers in the company a Slack message that summarizes all the updates.

More information

-For each update, we want to add a link to the page in Storybook so the designers can access the page.

More guidelines:

  • Each point should be clear and concise.
  • The tone of voice should be informal.

The updates:

  1. The Design System Team is proud to announce the release of a new card component. The new card component is designed to enhance the overall user experience by offering a sleek and modern design that provides a clear and concise display of information. The new card component includes an updated layout with a responsive design that will adapt to different screen sizes, making it easier to use on mobile and desktop devices. Additionally, the team has included various options for customizing the card, including the ability to add an image, header, and footer.
  2. The Design System Team has made updates to the color palette to improve accessibility for users with color blindness and other visual impairments. The new palette features an increased contrast ratio and updated color values, making it easier for users to distinguish between different elements on the page.
  3. The Design System Team has added new possibilities to the table component, allowing users to display more information in a clear and concise manner. The updated table includes the ability to sort columns, add pagination, and filter data. The team has also made improvements to the layout of the table, making it easier to use on smaller screens, and included various customization options, allowing users to personalize the table to their specific needs.
  4. The Design System Team has updated the select component with a new design with an improved user interface, making it easier for users to make selections. The team has also added a new size S, ensuring that all users can use the component easily regardless of their device or screen size. The updated select component is designed to provide a seamless user experience and is a valuable addition to the design system.

Here is the response of chatGPT

Hey Designers! The Design System Team has some exciting updates for you:

  1. New Card Component: A sleek and modern design with a responsive layout that adapts to different screen sizes. Customizable with options to add an image, header, and footer. [link to card component page].
  2. Improved Color Palette: Increased contrast ratio and updated color values for better accessibility for users with color blindness. [link to select component page].
  3. Updated Table Component: Sort columns, add pagination, and filter data. Improved layout for smaller screens and customization options. [link to table component page].
  4. New Select Component and Size S: Improved design with a user-friendly interface. [link to select component page].

Let us know what you think!

Using prompts for UX writing tasks

Often, many companies do not have a UX writer on the team, so the product designers write the microcopy. Because it is not a daily task, it can take time, and in many cases, the designers write the message without following the design guidelines.

To solve it, you can write a clear prompt so they can run it and get many ideas for messages in one click.

Let’s take this case for example:

The Prompt

I am a product designer working on a subscription-based product. We have this case in the system “the user forgets to update a credit card, and the card is out of date.”

Can you provide an email explaining why this happened and what he can do to solve it?

Here are the guidelines:

  1. Be concise and clear.
  2. Use plain language.
  3. Indicate the cause of the error.
  4. Provide a solution or next steps.
  5. Be empathetic.
  6. Avoid blaming the user.

Here is the response of chatGPT:

Subject: Action Required: Update Your Payment Information

Dear [Name],

We hope this email finds you well. Our records indicate that your credit card on file for your subscription with us has expired. As a result, your subscription has been suspended.

You may forget to update your payment information due to a busy schedule. We understand. This is a common issue, and we’re here to help.

To reactivate your subscription and ensure uninterrupted service, please update your payment information as soon as possible by logging into your account and navigating to the “Billing” section. You can easily update your credit card information and resume your subscription with just a few clicks.

You can contact our support team for assistance if you have any questions or concerns. We will be happy to help. We value your business and are committed to providing you with the best possible experience.

Thank you very much for your prompt attention. We look forward to continuing to serve you.

Best regards,

[Your Company]

You can see that it is not perfect, and you need to work on it, but you do not have to start from a blank page can save you a lot of time when you need to create content.

💥 Pro tip: adding some examples of messages from your system to the prompt can help the AI to create more accurate text for your system.

Using prompts for UX writing tasks
Using prompts for UX writing tasks

Use it as a tool to ask questions

Sometimes you need to find information about the product you are working on in the design system documentation or elsewhere. Finding information takes time, and sometimes you must read a lot of information before finding a simple answer.

In the future, we could add artificial intelligence to the product documentation. Then, you only need to ask in the search field or an AI powered chatbot what you’re looking for without reading all the details. This way, it is easier to quickly find the answers you need, as the AI can quickly scan through all the product documentation and identify the relevant information.

Imagine this case, you’re new to the company and don’t know how to use the icon group properly. You can ask this question a designer from your team, or you can navigate to the page and read the information or ask another designer.

Alternatively, you can ask the AI chatbot a question and get a straight answer. It seems a small change, but the experience is a lot better.

Design system documentation assistance with AI chatbot
Documentation assistance with AI chatbot

To summary

In this blog post, I wanted to explain how you can use ChatGPT to create and maintain design system documentation.

I began by explaining why we should not be afraid of using AI tools like ChatGPT or another AI model and how we can use these tools to improve our workflow. Then we reviewed how the tools can help generate a basic structure for the document, help with writing ux copy, simplify complex text, write design tokens, and find information.

However, the process can be sped up with artificial intelligence tools, but reviewing the information and customizing its content creation to fit your design system needs is essential. Although AI tools can replace some tasks, they cannot replace human judgment and decision-making.

And lastly, don’t worry; AI won’t take over the world soon — it can’t even figure out how to make the ideal cup of coffee yet! 😀

Learn AI for Product Design: Enroll in my Upcoming Course

In this context, I would like to mention that I plan to launch a workshop in the near future showcasing different uses for AI writing and image generator tools.

If you’re interested, please enter here.

Source link