[Proposal] With all class names, find a balance between consistency, ease of use for newcomers, and ease of customization

[AlexVipond]

I've seen this discussion pop up in a bunch of other threads both here and on Twitter. Just wanted to open a dedicated issue so we can give it proper consideration as we approach Tailwind 2.0.

General idea: people have proposed moving to linearly incrementing, number-based class names (text-1, text-2, etc.) instead of word-based class names (text-xs, text-sm, etc.) and non-linearly incrementing number-based class names (m-10, m-12, m-16, m-20, etc.).

I've experimented a lot with this and have given some thought to the trade-offs. From what I've seen, we all agree that these things are important:

• Class names should be reasonably consistent across all of Tailwind
• Tailwind should be easy for newcomers to use
• Tailwind should be easy to customize

And here's how the class naming systems stack up in terms of those priorities:

Word-based

Pros:

• Arguably the easiest naming system for Tailwind newcomers. T-shirt size classes like text-xs in particular feel super intuitive.
• Easy to be semantic, e.g. tracking-wide and leading-relaxed.

Cons:

• Hard/impossible to find names for custom, in-between values (xs.5? small-and-a-half?). Right now, this is why spacing utilities completely ditch the words altogether and go with a scaled number-based approach.
• Easy to fall into the trap of making words inconsistent across different properties. Case in point: text-lg, tracking-wide, and leading-relaxed are all next size up from the default size.

Numbers that always increment by 1 (or 100)

Pros:

• Arguably the easiest naming system once you get past the initial Tailwind learning curve and get acclimated to the Tailwind way of designing things.
• You can use -0 to "unset" all properties, instead of trying to remember which should be -none and which should be -0.
• Very easy to name your custom values.
• Extremely easy to guess the "next" class when you're designing and just need to bump the size up or down for any given property. mt-10, mt-12, and mt-16 become mt-8, mt-9, and mt-10.

Cons:

• Not always easy to remember where the "default" value is. When you apply this naming scheme to all properties, the default font-size becomes text-3, the default border radius becomes rounded-2, and the default shadow becomes shadow-1.
• Not easy to guess how much your design will be affected by incrementing the class name. With mt-10, mt-12, and mt-16, you have a sense that you're adding progressively larger amounts of spacing, but with mt-8, mt-9, and mt-10, you'd expect linear increments in the underlying spacing values, and you might be confused when that doesn't happen.
• Sucks for opacity. Don't ever make me use something other than opacity-25 for opacity: 0.25.

Numbers that always increment based on the change in the underlying values

Pros:

• Keeps you grounded in how much size you're adding to a design. mt-10, mt-12, and mt-16 make it clear that you're adding progressively larger amounts of spacing.
• Very easy to name your custom values
• You can use -0 to "unset" all properties, instead of trying to remember which should be -none and which should be -0.

Cons:

• Sometimes difficult to remember, even for Tailwind veterans.
• Big learning curve for Tailwind newcomers, who need to spend a lot of time in the docs until they start to remember that mt-32 exists, but mt-36 does not.
• Keeps you grounded in how much size you're adding to a design. This is both a pro and a con—the downside is that it forces you give some thought to the underlying values in Tailwind's design system, which are implementation details for Tailwind users who aren't customizing the system.

[mrcsmcln]

I've been thinking about this a lot the past few months. There's a certain amount of granularity that string-based class names don't provide. In theory, it's pretty easy to move toward number-based class names, but it comes with a catch: the scale (i.e., multiplier) is going to be different for each property (e.g., margin versus letter-spacing). Furthermore, some value ranges are bounded (e.g., opacity), so they'd likely need to be handled differently.

That being said, I've been incrementally adopting number-based based classes on my new projects out of necessity and it's been working great, but only once you get familiar with the different scales. I can't imagine the new developer experience is too great using this approach, but I could be wrong. Let's just take line-height, letter-spacing, and opacity as an example:

{
  letterSpacing: {
    // Formula: 200 * letterSpacing (e.g., 200 * 0.015em -> 3)
    '0': '0',
    '1': '0.005em',
    '2': '0.01em',
    '3': '0.015em',
    '4': '0.02em',
    '5': '0.025em',
    '6': '0.03em',
    '8': '0.04em',
    '10': '0.05em',
    '12': '0.06em',
    // and so on
  },
  lineHeight: {
    // Formula: 20 * (lineHeight - 1) (e.g., 20 * (1.2 - 1) -> 4)
    // Question: what do we do for line-height < 1?
    '1': '1',
    '2': '1.1',
    '3': '1.15',
    '4': '1.2',
    '5': '1.25',
    '6': '1.3',
    '8': '1.4',
    '10': '1.5',
    '12': '1.6',
    // and so on
  },
  opacity: {
    '0': '0',
    '20': '0.2',
    '40': '0.4', 
    '60': '0.6',
    '80': '0.8',
    '100': '1',
  },
}

In this case, the numbers are consistent with theme(spacing) (with the exception of opacity, which makes sense to keep it that way), but the scales are defined completely differently. There's definitely some mental math gymnastics going on here when you're using them, but if you've got well-defined components (e.g., .type-h1) that inherit these properties and you're using them globally, you only need to think about it once and then simply apply it everywhere.

On a more philosophical note, I find that the front-end development process happens in this order:

1. Develop the supplied design using pixels as your guide
2. Fill in the blanks with what looks good using feelings as your guide

So once the pixel-perfect design has been coded, the developer needs to go with their gut. That's where having a consistent yet granular scale comes in super handy. This is especially true for properties like transition-duration, where a small change can make or break an experience.

Overall, I really like the idea of making Tailwind class names number-based as I find it incredibly useful, but I do worry about the initial developer onboarding experience a bit.

[adamwathan]

Hey folks! Really appreciate the level of thought put into this.

If I've learned anything working in and with open-source though it's that end-users value stability/backwards compatibility extremely highly, and breaking changes need to correct some really fundamental problem that frustrates/limits a large portion of the user base to be worth it.

Put another way, just because a breaking change is an improvement, it doesn't mean it's automatically worth doing — in fact in my experience working on Tailwind itself a breaking change has to be a really significant improvement to even be worth considering, because even if a class name isn't perfect people will still learn it and get used to it and it becomes a really superficial "problem". I went down this road trying to improve the leading and tracking utilities from 0.x to 1.0 and ultimately after weeks of hashing it out with the community it made the most sense to just stick with what we had and live with it because it just wouldn't have improved anyone's lives enough to be worth adding the extra friction in upgrading to 1.0.

So for that reason I'm not planning to make any drastic changes like this to the current naming conventions until it feels like it's a really huge problem that's causing people lots of pain, because I believe the silent majority care more about things being stable than being perfect.

On the same note I decided recently that I'm actually not going to push forward with a v2.0 any time soon, and will instead just include the transforms, transitions, and grid features into v1.2 so folks can upgrade without having to worry about anything breaking. Ideally I'd like to get the new {color}-50 values and the small color palette adjustments into a minor release as well, but since that will affect how people's projects look I'm going to eventually open another discussion about that and find out if people are actually worried about that from a "breaking change" perspective, especially since it won't actually "break" anything since no class names are changing.

[AlexVipond]

Sounds good to me—glad to have this issue to refer back to, since this topic seems to pop up every time a new core plugin is introduced.

For anyone stumbling across this who's really gung-ho about linear numeric naming, I had some fun exploring what kind of NPM package would make it really easy for users to configure this kind of stuff on their own—here's what I came up with.

And here's the source code for anyone who wants to use a similar approach to create their own custom naming conventions 🤖