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

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

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:

Here is a text from a design system documentation. Can you write in the shortest way possible?

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:

Theme.Component.Size.State.Color

The variants are:

Theme: Dark, light

Component: checkbox

Size: Small, Medium, Large

State: Enable, Disable, Focus, Hover

Color: Background, Border

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.

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:

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.

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.

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.

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.

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:

Be concise and clear.

Use plain language.

Indicate the cause of the error.

Provide a solution or next steps.

Be empathetic.

Avoid blaming the user.

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.