ChatGPT prompts for your component’s design system documentation

Everyone is talking about AI this and AI that. It’s clear that AI isn’t going anywhere, and the world is just scratching the surface of how we can leverage it. There’s talk about AI and design systems, which we’ll discuss in upcoming blog articles.

To kick things off, we wrote a ChatGPT prompt to help you quickly document components in your design system. We’ve done the heavy lifting for you, so you can cruise along and swiftly document more of your design system.

A quick ChatGPT overview

If you’re unfamiliar with ChatGPT, it’s an AI-based chatbot created by OpenAI. It’s free to use, and they have paid tiers. When you message ChatGPT with questions, it’ll quickly provide an answer – and how much it knows and can do is remarkably impressive!

It’s all about the prompt

A prompt is a message you send when asking ChatGPT to generate a response, like written content, code, ideas, etc. How helpful ChatGPT’s answers are will depend on how well-crafted your prompt is—typically, the vaguer your prompt, the less valuable the response. Sometimes you can over-rotate and be too specific, yielding unhelpful responses. So it’s all about defining just enough in a prompt that ChatGPT can be helpful. Tweaking the prompt can take a while, but guess what? We did it for you! We experimented with prompt details and tweaked wording to get ChatGPT to produce component documentation suitable for most design systems.

The prompt

Alright, let’s get to the good stuff.

Step 1. Start a new conversation with ChatGPT.

A new conversation will mean it’s starting with a clean slate and no previous prompt baggage.

Step 2. Establish the context.

To avoid having to enter this context over and over, we kick off a conversation with ChatGPT to establish that we will be asking it to create design system documentation based on some vital context.

Copy and paste this as your first message to ChatGPT.

I will ask you to create design system documentation pages for components in my design system. For each prompt, the output should be a page that documents that component. The content should be written from the perspective of a senior-level design system designer. The audience who will read the documentation includes: designers, developers, and content designers who are new to the company, have entry-level experience, or are seasoned professionals. The voice and tone should be professional yet casual, written in plain language, and concise. The priority is to use bulleted lists instead of paragraphs.

ChatGPT should respond, saying it understands and is ready to go! (In rare instances, it might give you some design system documentation. If this happens, tell them this isn’t what you wanted.)

Step 3. Send over your first request for design system documentation

Copy and paste the prompt below, which is set up to return design system documentation for a component. If you skim the headings of the prompt (i.e., H2 and H3 lines), you’ll see it should output information regarding usage, do/don’t rules, content, accessibility, and more. It’ll also recommend opportunities to include images to illustrate things. You’ll have to create those images on your own – hey, it can’t do everything for you… yet. 😉

Before sending the prompt to ChatGPT, you must do one or two things.

1. In the first sentence, replace “[component name]” with the name of the component you want to document.
2. In the second sentence, if that component has different types, include the number of types and their names. You can delete the second sentence if the component has no types.

For example, if you’re trying to document buttons. The prompt’s first two sentences would be:

“I need a design system document page for the button component. There are 4 component types of the button component: primary, secondary, tertiary, and icon-only.”

Once you specify those things, send the prompt to ChatGPT and watch the magic happen.

Prompt:

I need a design system document page for the [component name] component. There are [X] component types of the [component name] component: [list the names of the component types]. Please indicate where images will be helpful to illustrate examples, especially for do/don’t pairs.

The documentation page should include the following:

H1: Component Title
Provide a one-sentence description of the component.

H2: Usage guidelines
Provide general usage guidelines.

H3: When to use
Provide scenarios of when to use the component.

H3: When not to use
Provide scenarios of when not to use the component.

Looking at the when to use and when not to use scenarios, summarize any do/don’t usage pairs and provide image ideas for them. (I’ll make the images based on your feedback.)

H3: Using variants
Go through each component type and include their definition and purpose, including when someone might use that component type.

H2: Formatting
In the Formatting section, include the following as applicable:

• Anatomy
• Sizes and their use cases
• Emphasis and their scenarios
• Alignment and their scenarios
• Other layout options like grouping

H2: Style

H3: Color
For each component type, provide a list of scenarios where different colors would be used.

H3: Typography
For each component type, provide a list of typography styles.

H3: Structure
For each component type, provide a list of recommended specs for spacing, padding, margins, and size variations.

H2: Content
Provide content design guidelines regarding labels, lengths of text recommendations, wrapping or truncation scenarios, and content patterns. Provide do and don’t examples for each of the recommendations. Indicate when a visual would be appropriate for the do/don’t pair.

H2: Behaviors
As applicable, for each component type, provide a description of how the component behaves when the user or system interacts with it. Some behaviors include states. Provide other things to consider around behaviors that I might not have thought of

H2: Modifiers
Provide details about any modifiers available in the component or component type. Consider any that I might not have thought of before.

H2: Accessibility
For accessibility, I need you to provide details around four aspects: interactions, what the design system provides, what the developers need to consider and are responsible for, and what the designers need to consider and are responsible for.

H3: Interactions

H4: Mouse
For interactions, provide details on how a user would interact with the component or component type if they only used a mouse.

H4: Keyboard
For interactions, provide details on how a user would interact with the component or component type if they only used a keyboard.

H3: What the design system provides
Provide details on what the design system provides.

H3: Development considerations and responsibilities
Provide details on development considerations and responsibilities for accessibility. This can be for the developer creating the component or using the component in a product. Include anything I didn’t think of.

H3: Design considerations and responsibilities
Provide details on designer considerations and responsibilities for accessibility. This can be for the developer creating the component or using the component in a product. Include anything I didn’t think of.

How did it go? It might not be perfect, but consider how long it took to generate the documentation compared to how long it would have taken to write it from scratch. Pretty rad, right?

Step 4. Rinse and repeat

You can do even less work if you’re ready for ChatGPT to document another component!

Copy and paste the follow-up prompt below, change the component name, and if applicable, include the component types there are.

Nice work! I need a design system documentation page in the same format for the [next component name] component (and it has [X] component types: [list component types]).

Then send it off and watch some more magic happen!

Making this work for your design system

As much as we want AI to do our work for us, it has limitations. First, if you’re using the free version of ChatGPT, it’s using version 3.5, whose knowledge only goes till mid-2021. So it won’t know anything recent. It won’t know specifics about your design system, so it might not include the details you want in your documentation. It’s also possible that it could make up information. Untrue information generated by AI is known as “AI hallucinations.”

With this in mind, there are a few things you should do:

1. Include more specific details in the prompt. We created this prompt to serve a broad use case. Chances are, you have specific information or exact do/don’t guidelines you want in the documentation. List those details in the prompt’s appropriate section to ensure ChatGPT includes them.
2. Validate the information generated. AI hallucinations can be entertaining but are dangerous if you don’t fix them. Read through what it wrote and make any edits. Editing is still so much easier than writing things from scratch.
3. Remove unnecessary information. Sometimes ChatGPT will include general design guidelines for a component that is helpful if you’re designing the component. For example, “Use a solid color for the primary button.” While it might be correct, that’s not information a consumer of a design system needs. That decision was already made as part of the design system. Feel free to be ruthless with editing this information. It might also include information irrelevant to how your organization should use the components. While this info could be correct, don’t include it if it doesn’t exist in your product or design system. When documenting, we like to focus on recording current details instead of “one day, we might…” scenarios.
4. Consider any new thoughts and ideas that ChatGPT generates. This isn’t to contradict our last point of removing things. Sometimes ChatGPT will include a different perspective on things you didn’t consider documenting. For example, it might contain details around the spacing between two stacked radio button components, which wasn’t on your radar. Since that’s a scenario that’s part of your design system, you might want to consider including that spec in the documentation.

Even if you have to do some extra work, the effort is much quicker than creating content from scratch. ChatGPT help is especially beneficial if writing isn’t your forte, you’re short on time, or you would rather spend time doing other fun things.

Try it and let us know!

We’d love to hear how this prompt worked for you. Did ChatGPT score big, or did it completely miss the mark? Did anything funny come out of the responses?

Feel free to share on social media and mention us on LinkedIn, Twitter/X @zeroheight, or zheroes, our Slack community.

If you want another framework for documenting more of your design system, check out our other article, “Using AI for Design System Documentation.”