The single, guiding question for all your product designs

I received a comment on a previous issue that made me a little sad.

The comment read, “I love this. This seems so easy as I read along with the explanations and changes you made after the fact. But wonder if it's something I can do myself and I think the answer is no.”

I’m glad she loved the issue, but I really want the answer to that question to be “yes”. I want you to feel empowered and capable of going through the design process on your own.

So I’m going to approach this issue a little differently.

We’re going to do the same change-by-change breakdown we always do, but this time, I’m going to see if I can bring it back to one guiding question, a question you can ask yourself for your own design sessions.

Let’s go!

When we styled Open AI’s documentation last issue, we removed a key element from the docs – the tags.

In this issue, we’re going to bring them back and style them. Let’s pick up where we left off with the addition of our unstyled tags.

Here’s our starting point:

By “tags,” we’re referring to the unstyled, second line in each list item.

Before we begin some fun styling, let’s cover the basics with a simple, starter question.

Is my content even readable?

As far as readability, I’d say “no.” The way the tags are laid out, I can’t tell if “number or null” is one idea or three. We need better spacing. Let’s add some margin to make our tags more readable.

Here’s the before and after:

Much better!

Now we get to the fun stuff 🙂

What’s the job?

First, let’s establish the role these tags play on the page.

Their job is to help the user better understand how to use the param. They’re secondary, supporting information, which means that they shouldn’t compete with our param for our attention – the param is the star of the show. Instead, they should fall into the background, waiting to be called on.

Remember that guiding question we started this issue with? Let’s introduce it.

“Does my design help the tags do their job?”

This is the question we’re going to keep coming back to, and that you can keep coming back to, as we walk through this together.

In its current state, I would answer: “No.”

Why not? What looks off?

To that, I’d answer: “The tags are competing too much with the param. They should take up less space. They should feel smaller.”

Great! How about literally making them smaller?

Revisiting font size

Let’s play with font size and add the class “text-xs” from Tailwind to our tags.

Great. Now that we’ve updated our design, let’s go back to our question:

“Does my design help the tags do their job?”

Hm, sort of?

Okay, what looks off?

The tags’ job is to support the param, but visually, they take up a whole line by themselves, making them feel more important and independent than they are. It makes sense that the description would take up its own line since it’s distinct, but the tags don’t feel quite important enough to take up that much space.

Playing with positioning

This sounds like a good opportunity to play with layout and positioning. If the param feels like it’s more of an augmentation of the param than its own distinct element, how about we literally move it closer to the param?

Let’s try putting them on the same line.

I love this change. By having the tags follow the param, it gives our user permission to ignore them unless they become relevant. As our eye travels down the page, we’re drawn to the param and, once we find the right one, we can keep reading and see its supporting information.

Let’s add “make it inline” to our toolkit of things to try for future design projects.

Back to our guiding question: Does my design help the tags do their job?

I would say this design helps the tag play their role, but I think we can help it even more.

Let’s get tag-y

Tags are a very common design element. We see them everywhere across screens. But our tags here don’t look very “tag-y.” But do they need to?

I would argue “yes.” It’s easier to communicate the purpose of an element when it looks the way you expect. Users know what a tag does and what it’s supposed to look like. By showing them an element that looks like one, we’re making it easier to understand its purpose.

So in order to help our tags do their job, I’m going to try to make them look more “tag-like.”

This is where we cheat – shhhhh, don’t tell 🤫

Because tags are everywhere, we don’t need to start from scratch to figure out how to design them. Let’s find some inspo.

To do this, log in to the products that you use and see how they approach the same element. If you can’t think of where to look, Dribbble is a great source of inspiration for a wide range of UI elements. Just search for “tag” and filter by “web design” or “product design.”

Here are a few I found from products that I use.

Although these are all tags, their context is different from ours, so the style might not work for our purposes. Let’s look at our collection and see what might makes sense for us.

Instead of trying out each option, let’s try to rule out some options by just talking through them.

Let’s update our guiding question from, “Does my design help the tags do their job?”, to “Would this design help the tags do their job?”.

Let’s look at the first one:

So let me ask you:

Aesthetically speaking, I like the look of the colored background and the colored text, but given that the tags would be the only colored things in our documentation, I think that would make it stand out just a bit too much. I think we can do better.

What do you think of this one?

I must admit that this isn’t the most exciting styling for tags I’ve seen, but it feels very functional. For our purposes, we would remove the “x” meant to delete the tag since the user isn’t interacting with the documentation. But I can see how gray text on a light gray background would keep our tags in their supporting, secondary role but still help them look like tags.

Let’s look at the next one:

Hm, maybe? To be honest, I’m not quite sure. There is some color, which could be distracting, but it’s just the text and not the whole background, so maybe it would be okay. We could also try the gray border and keep the font color gray too. Definitely something to consider.

Last one!

These tags don’t feel right. They remind me a lot of social media tags, which is a different context than the one we’re in. I think we can do better.

We haven’t picked a final style, but we did narrow it down. By asking one key question, the same question we’ve been asking this whole time, we ruled out options and made our process a little faster.

Instead of an endless list of CSS attributes to test and fiddle with, we have two styles to pick between. Much easier!

Let’s implement the first one. We can break down this style to its key components:

• Light gray background

• Dark gray text

• A bit of padding

• Rounded corners

Easy enough! Let’s implement this using Tailwind.

Here’s the sample code:

<span class=”mr-4 text-xs bg-gray-200 text-gray-700 rounded px-2 py-1”>number or null</span>

And here’s the result:

Let’s revisit our guiding question.

The good news is that our tags are looking very tag-like, but they feel a little too prominent for me. I want them to settle into the background a bit more.

Let’s try the second option and see how we feel.

For our second option, we’re going to do the following:

• Add light gray border

• Round the corners

• Change the text color to dark gray

Here’s the sample code:

<span class="mr-2 text-xs border border-gray-200 rounded text-gray-500 rounded px-2">number or null</span>

And here’s the result:

Looking good!

But let’s remember – it’s not about looking good, it’s about doing the job. So let’s revisit our question: “Does this design help the tags do their job?”

The answer to the question for me is “yes.”

In this design, our tags:

• look like proper tags, which makes their job clearer to the user

• fall into the background more easily since we only added a subtle border

• lean into their secondary, supporting role by being inline next to the param

But how did OpenAI style it? Let’s compare our final design with what’s live on the site:

They’re pretty similar, but OpenAI made a few different decisions. They decided to:

1. keep the tags as simple words with minimal styling

2. use a different typeface instead of font weight to draw the eye to the param.

Which ever you like better, I’d say they both help our tags, and our documentation in general, do their job well. And now you’ve got two different approaches in your tool belt for a future documentation project!

Let’s end with some key takeaways for your next design project:

How to use this in your next project:

1. Use the guiding question
   Throughout this process, we kept coming back to one key question you can ask yourself: “Does this design help the element do its job?”
   
   If the answer is “no” or maybe “not all the way,” try and spend some time thinking critically about the job of the element and what feels off to you about the current design.
   
   Thinking is just as important as pushing pixels.
   

2. Don’t forget about positioning
   My favorite decision in this design process was placing the tags next to the params.
   
   Positioning and layout may not be the first things you think of when it comes to design, but they’re super helpful tools that can create order and organization. Make sure to keep these tools in mind.

Hopefully this issue gave you a few more tools in your design tool belt and a powerful new question to help you get to the next step in your design process.

Sneak peek 👀

I’m working on an issue dedicated to the very popular, and often default, typeface, Inter.

I want to understand what makes this typeface so special, where it came from, and how it became so widespread.

So I reached out to the creator of Inter for an interview and he said yes! It means creating some of our first video content, which I’m a little nervous but excited about! Stay tuned 🥳

Happy designing!

❤️ Saron