Proper Class Order to Reduce Cognitive Load

[sir-kokabi]

Problem:

The way Tailwind classes are organized can really affect how much mental effort a user has to put in, especially if they're just starting out. Unfortunately, this important detail often gets missed in the current documentation examples. If the classes were arranged in a way that their visual effects became more apparent over time, it would make it so much easier for users to see what each class does. They wouldn't have to keep going back and forth, removing or re-adding classes just to figure things out.

Example:

Let’s take the following code as an example:

<div className="mx-auto max-w-sm border">Hello</div>

• Step 1: When we add mx-auto, you won’t see any visible change right away. The element still stretches across the full width of its container, so there’s no clear sign of the centering effect just yet.

• Step 2: Next, when we introduce max-w-sm, there’s still no immediate visual difference. The width limitation doesn’t really show its impact until we add something like a border or background color.

• Step 3: Finally, once we add the border, the change is clear. Now we can see the div framed by a border, and the effects of the earlier classes (mx-auto and max-w-sm) start to come together.

However, to fully grasp how these classes work, we might need to revisit them. For instance, if we remove and then reapply the classes, we’ll have to reassess their individual effects, which can add a bit of mental strain.

Solution:

This issue can be easily fixed with a simple tweak in the documentation: whenever possible, we should organize the class order so that the visual effects of each class are clearly displayed as they're introduced. This approach allows users to grasp the impact of each class step by step, making it much less confusing.

<div className="border max-w-sm mx-auto">Hello</div>

• Step 1: As soon as we add border, we instantly notice a border appearing around the div. This is the first visual cue that makes the changes stand out.
• Step 2: Then, when we introduce max-w-sm, the effect of limiting the width of the div becomes clear. The border helps us see the size change more effectively.
• Step 3: Finally, by adding mx-auto, we can observe the div centering itself horizontally. With the width already constrained by max-w-sm, the border gives us a clear visual indication of the centering.

This sequence makes the visual impact of each class easy to grasp, allowing users to follow the design process step by step.

Conclusion:

By organizing utility classes in a way that highlights their visual effects right away, users can grasp the impact of each class much more easily. This approach lightens the cognitive load and makes working with utility classes feel more intuitive, especially for those just starting out. Sure, there are instances—like with breakpoint-related classes—where the visual effect isn’t obvious until the screen size changes, but that doesn’t take away from the benefits of this method whenever we can apply it. I believe we should seize every chance to enhance the clarity of our documentation, even if it doesn’t solve every issue perfectly. Those little tweaks can really transform the learning experience.

[philipp-spiess]

Hey! The class order in our docs as well as the playground is based on https://github.com/tailwindlabs/prettier-plugin-tailwindcss and they're ordered based on the order they will appear in the CSS file. This can help you notice issues where some utilities take precedence over other utilities (e.g. in this case: <div class="m-0 ml-2"></div> you can see that ml-2 would overwrite the more generic m-0).

I'm not quite sure I follow your argument for reordering as well. Are you implying that people copy the examples by typing each class name into an editor and saving after every class name? In my experience, people just copy paste stuff but maybe I misunderstand.

[sir-kokabi]

Hey @philipp-spiess,

Most folks have Auto Save turned on, so there’s really no need to hit save after every class. 😉

And even if someone copies code from the documentation, if they’re not familiar with Tailwind, they’ll still need to grasp what something like ml-2 actually means. How do they figure that out?

Typically, they’ll take off the class and put it back on just to see how it looks. Sure, the documentation lays out what each class does—but visual trial and error is a huge part of the learning process, especially for beginners. It’s a lot like how we often use console.log or print statements when debugging—because seeing something in action really helps it click.

That’s exactly why the hero example on the Tailwind homepage is so effective—it demonstrates how each class visually contributes to creating a polished UI, step by step.

I think the suggestion I made aligns perfectly with this philosophy. It’s not about plugins or tools—those are different issues. Sure, a plugin might later rearrange classes based on CSS logic or sorting preferences (like how minifiers compress code), but that’s separate from how we present examples for learning.

In documentation, class order should focus on learnability. If tweaking the order a bit helps cut down on those “I made a change—why didn’t anything happen?” moments, then it directly enhances the learning experience and helps people understand Tailwind more quickly.

Ultimately, anything that reduces friction and clarifies how utility classes work is worth pursuing—especially if the only cost is reordering a few non-conflicting classes in examples.