Styling text-based lists

When it comes to lists, particularly text-based lists (ex: documentation or bullets in a blog post), I don’t think much about how they’re designed.

They feel like just another piece of content. I might give the bullets a color, but besides that, they don’t scream out as elements that need much design attention.

What about you?

But every once in a while, I’ll notice a list that doesn’t look like a hastily thrown together <ul> element that I would create.

The list looks … good.

In fact, it doesn’t look like a list at all. It looks like a thoughtful component intentionally laid out on the page. Nothing wild or over-the-top, but just a touch of style that makes it appealing but still highly functional.

I want to learn how to make my lists look like that.

So let’s dig in and see if we can figure out how to style our lists together.

Let’s start with a basic HTML list.

Here’s some unstyled documentation from OpenAI. For simplicity’s sake, I’ve removed the group of words that look like tags meant to describe the param (like “number or null, Optional, Defaults to 1”) that are found in the real docs.

Now, I don’t know about you but, without styling, this list is hard to navigate, if not overwhelming. I’ve only picked three items, but imagine scrolling through a whole page of these – that would be a lot!

So how can we style this list to make it easier for our users?

Remember, we’re not striving for design per se – we’re striving for organization and trusting that good design will come from that.

So let me start by asking you – what about this list makes it feel disorganized?

For me, one thing is the fact that I can’t easily tell each item apart. They all kinda run together as one long, ongoing list instead of a list with distinct items.

How can we fix that?

I have two ideas. Let’s see which one we like best.

Good spacing

Idea #1 is playing with spacing.

The reason why the items flow together is because the space between the lines and the space between the items is the same. Let’s change that.

Let’s make the space between the items bigger. There are several ways you can do this. Since I’m using Tailwind, I’m just going to add the class “mb-8” to the first two <li> items.

Here’s how it looks:

Ahh, that feels so much better!

But I want to try one more thing to see if I can double down on that separation.

Drawing lines

Let’s try idea #2: adding a line between each item, a literal separator.

I’ll do that by adding a bottom border to each <li> element and adding some margin and padding to let the border breathe.

The code looks like this:

<li class=”mb-8 border-b-2 border-gray pb-8”>

Here’s the result:

I like it!

Each item feels like its own, individual entity, increasing the organization of the page.

That’s a great start, but where do we go from here?

Let’s revisit our goal.

The point of better organizing our page isn’t just because we like things neat and tidy – it’s because we want to help our users accomplish their goal.

For documentation, the goal of the user is to quickly understand how to use OpenAI’s API. In order to do that, they have to easily find what they’re looking for, understand how to use it, then get back to their editor and try it out.

In other words, we want to make our documentation “skimmable.”

How do we do that?

The first step is understanding what content we’re working with. We’ve got our list items, but what’s in them?

When our users are busy skimming, what are they hunting for?

Let’s break it down.

Our list items are made of two parts:

1. Param

2. Description of the param

Of these two, the param is the most important one – that’s the thing the user is hunting for. Positioning the param as the first thing you see in a list item is helpful, but besides that, as it stands, we’re not giving our star of the show its deserved spotlight.

Let’s change that and help our params stand out.

Here are three things we could do to our param elements:

• Change the color to make it pop

• Make the font size bigger

• Increase the weight

Let’s try all three and see what we think!

Playing with color

Since one of OpenAI’s accent colors is green, let’s start with that.

This does create that separation between the param and the rest of the information – “temperature” looks distinct from the rest of the content – but changing the color to something bright while keeping the rest of the content black comes with a problem.

While green and black are obviously different, the black is darker, which means it carries more weight. So while we’ve created separation, I don’t think we’ve called attention to the right piece of content, which doesn’t help us achieve “skimmability” in the way we’d like.

Changing the font color to a bright accent color is always a tempting first choice but doesn’t often work out the way we think. If we’re using black for our body, we end up with a colorful header that competes for attention and looks more washed out than distinct.

What if we change the font-size instead? What would that look like?

Go big or go home

Let’s try a bigger text size.

Hm, I guess this kinda works? The params do look distinct, but they don’t stand out as much as I want them to. But if I made them any bigger, they’d look obnoxious.

I’ve found that when I’m trying to emphasize something, increasing the font size rarely works out the way I hope either. I choose going home over going big for this one.

What about you?

And finally, we’ll try our last tool in our toolbelt: font weight.

Go thick or go home?

What would increasing font weight look like? Let’s try it and see!

That looks much better! The params stand out and are much more skimmable. I choose going thick!

But there’s one thing that’s bothering me – those bullet points.

When we started, those bullet points were an important way of letting us know that we were starting a new list item. They helped us organize our list.

But now that we’ve added the border and we’ve increased the font weight on the params, we don’t really need those bullets. In fact, I would argue that they detract from our “skimmability” goal by starting each item exactly the same way. (Fun fact: Tailwind by default actually gets rid of the bullets for you. To illustrate the default <ul> styling for our example, I had to add the class “list-disc” to my <ul> class!)

So let’s remove them.

That looks a lot cleaner. Your eye goes straight to the params, which is what we want.

Final results

Let’s compare the list we started with to where we ended up and take in all that we did.

What an improvement! We made a ton of progress with just a few thoughtful design choices. There’s more we could do, but this feels like a good stopping point. If you want to see the code, here’s a link to the gist.

So how do you apply this to your next project?

There’s a lot that went into our final result so I want to highlight some of the big takeaways to bring to your next project, whether it has a list or not:

• You can do a lot with black and gray. 
  We were able to create a lot of organization without reaching for any bright colors. Keep this in mind when designing.
  
  Colors can be a fun and helpful tool, but they can quickly get overwhelming. See if you can make things work with grayscale first.
  

• Understand the user’s job. 
  All the design decisions we made required us to first understand what purpose the list served. We’re writing documentation for an API and the goal is to quickly understand how to use it.
  
  We determined that “skimmability” was the name of the game and we made decisions based on that goal. In the end, optimizing for the job the user is trying to accomplish helped us end up with a design that looks way better than what we started with.
  

• Don’t be afraid to experiment. 
  When I look at great design, I always assume the designer just knew what to do. I personally don’t have the experience to simply know what’s going to work, so I need to try things and assess the results. Initially, this takes time. But eventually, it gets faster.
  
  When I first designed, I used to always reach for color to improve my screens. Now I know to try other tools first and usually end up with better results.
  
  But when you’re not sure, just try it out and see whether it works.

Sneak peek …

Now you might recall that we removed those tags from OpenAI’s documentation to simplify this example. What would the list look like if we added them back in? That’s coming up in the next issue 👀

I know this was a long post, but hopefully it was helpful! Was the length ok or should I try to make it shorter in the future? Let me know what you think! 🙂

Happy designing <3

Saron