Bug: max-w uses --spacing instead of --container

[gavar]

What version of Tailwind CSS are you using?
v4.1.4

What build tool (or framework if it abstracts the build tool) are you using?
TailwindPlay

What version of Node.js are you using?
N/A

What browser are you using?
Any

What operating system are you using?
Any

Reproduction URL
https://play.tailwindcss.com/cA87EpnMu8

@theme {
  --spacing-xs: calc(var(--spacing) * 1);
}

Describe your issue
The max-w-* utility classes currently use the --spacing-* variables for their width values. However, according to the official Tailwind documentation on max-width, these utilities are supposed to use the --container-* variables.

[philipp-spiess]

Hey! max-w-* reads from both of these namespaces (and also from --max-width-*). The --spacing-* one is considered the most-generic one that all spacing related utilities do read from too, see the implementation here: https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/src/utilities.ts#L995

Any particular issue that you run into with this?

[gavar]

Please see the reproduction URL.
If --spacing-* is considered the most generic, then I believe the order should be the following:

'--max-width', '--container', '--spacing',

instead of

'--max-width', '--spacing', '--container'

So, if we follow the logic from most to least generic it's likely to be:

• max-width-*
• container-*
• spacing-*

Not sure if placing --spacing-* before --container-* makes sense, it basically results --container-* being completely unreachable in case if you want to have semantic spacings like --spacing-xs for gaps or similar.

[philipp-spiess]

Yeah It seems like I looked at the wrong line, you're right in that --container-* is the more generic one. I still don't fully understand how this is an issue though 🤔 If you're overwriting --spacing-xs like in your example, shouldn't that enable the xs value for all spacing values? If we change the order, than the default --container-xs defined in theme.css would overwrite your custom variable here. Maybe I'm missing something?

However, according to the official Tailwind documentation on max-width, these utilities are supposed to use the --container-* variables.

Right but they do though? You can set --container-xs and it will overwrite the default: https://play.tailwindcss.com/48GZkur2SJ?file=css

[gavar]

Here's the potential workaround if someone is facing the same issue, thumbs up if you do.

@theme inline {
  --width-3xs: var(--container-3xs);
  --width-2xs: var(--container-2xs);
  --width-xs: var(--container-xs);
  --width-sm: var(--container-sm);
  --width-md: var(--container-md);
  --width-lg: var(--container-lg);
  --width-xl: var(--container-xl);
  --width-2xl: var(--container-2xl);
  --width-3xl: var(--container-3xl);
  --width-4xl: var(--container-4xl);
  --width-5xl: var(--container-5xl);
  --width-6xl: var(--container-6xl);
  --width-7xl: var(--container-7xl);

  --min-width-3xs: var(--container-3xs);
  --min-width-2xs: var(--container-2xs);
  --min-width-xs: var(--container-xs);
  --min-width-sm: var(--container-sm);
  --min-width-md: var(--container-md);
  --min-width-lg: var(--container-lg);
  --min-width-xl: var(--container-xl);
  --min-width-2xl: var(--container-2xl);
  --min-width-3xl: var(--container-3xl);
  --min-width-4xl: var(--container-4xl);
  --min-width-5xl: var(--container-5xl);
  --min-width-6xl: var(--container-6xl);
  --min-width-7xl: var(--container-7xl);

  --max-width-3xs: var(--container-3xs);
  --max-width-2xs: var(--container-2xs);
  --max-width-xs: var(--container-xs);
  --max-width-sm: var(--container-sm);
  --max-width-md: var(--container-md);
  --max-width-lg: var(--container-lg);
  --max-width-xl: var(--container-xl);
  --max-width-2xl: var(--container-2xl);
  --max-width-3xl: var(--container-3xl);
  --max-width-4xl: var(--container-4xl);
  --max-width-5xl: var(--container-5xl);
  --max-width-6xl: var(--container-6xl);
  --max-width-7xl: var(--container-7xl);
}

[marcospgp]

woah

[gavar]

@philipp-spiess any updates or comments on that?

[mzronek]

I have the same issue.

This is what i see in my project:

.max-w-md {
    max-width: var(--spacing-md);
}

This is what the documentation states: https://tailwindcss.com/docs/max-width

.max-w-md {
    max-width: var(--container-md);
}

[eriknaslund]

First of all thanks @gavar for the workaround - it was a lifesaver!

I don't have the solution, but I have one more piece of troubleshooting data.
I upgraded from TailwindCSS v3 to 4.1.10, went with CSS based config, and had the following theme config (I removed --color and --font related variables):

@theme {
  --spacing-0: 0;
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  --spacing-xl: 4rem;
  --spacing-icon: 1.5rem;
}

The emitted CSS looked like this:

  .max-w-2xl {
    max-width: var(--container-2xl);
  }
  .max-w-4xl {
    max-width: var(--container-4xl);
  }
  .max-w-lg {
    max-width: var(--spacing-lg);
  }
  .max-w-md {
    max-width: var(--spacing-md);
  }
  .max-w-xs {
    max-width: var(--spacing-xs);
  }

As you can see the sizes I've specified spacing- values for get overridden with --spacing-<size>, while the other are given the expected --container-<size>.

Perhaps this is expected behavior, but it was very counterintuitive to me, and from what I can see it wasn't mentioned in the upgrade guide.

I believe that in Tailwind v3 the "max-width" property seemed to approximate "container sizing" (large elements) while "w-" properties used "spacing sizing" (small elements). This seems to have been changed in v4. While I appreciate the consistency of having widths mean the same thing regardless of contexts I still think this could be worth of a notice in the upgrade guide.

As a workaround if you want to preserve the "v3 behavior" you can apply @gavar 's solution, but skip adding the --width-<size> lines, only add the --min-width-<size> and --max-width-<size> ones.

[Term164]

I have the same issue and I think the the order recommended by @gavar should be used.

This was really unintuitive and I was left scratching my head for a good 2 hours wondering why --spacing variables are overriding --container variables.

As @gavar already pointed out this makes --container variables unreachable.

Please do consider changing the order.

[jkinley]

Same here. I use Utopia for fluid type and spacing. I added custom spacing and it was breaking components in shadcn/ui. Very difficult to troubleshoot.

[lookdczar]

Just like the menu bar categorization on document pages, sizing variables should not utilize spacing variables. The value for spacing-md is generally not the same as that for width-md (i.e., container-md), and container-md needs to be much larger than spacing-md.

[r0busta]

This change #15180 is the culprit

And I think it's outright nonsence that contradicts Tailwind's own token system

We've been trained hard for years to use semantic max-w-{sm|md|lg|...} utils to restrict container width

But nobody mentions that customizing even a single spacing token destroys the layout because all of a sudden all containers in your layout start using that token and become squeezed into 2-4-8-Xpx width

This will hit vibe-coders especially hard if they ever try to use custom spacing tokens

[Der-Alex]

Today we also stepped into that pitfall. I think a good solution would be to differentiate between spacing and sizing, just as @lookdczar pointed out.

--spacing-xl: 2rem and -sizing-xl: 32rem could make sense in many cases. It would be totally fine if the default width and height values initially come from --spacing but having a simple solution to set a separate set of sizes for --sizing would be great.