Default theme variables appear to be incomplete

[endigo9740]

When reviewing the list of default theme variables:
https://tailwindcss.com/docs/theme#default-theme-variable-reference

Likewise looking at the source here, the follow do not appear:
https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/theme.css

There's no reference for the following properties:

• border-width
• divide-width
• ring-width
• outline-width

My expectation would be to see something like:

--border-*: '...';
--divide-* '...';
--ring-*: '...';
--outline-* '...';

This is present for, say, border radius which uses --radius-*:

And this is even called out on the individual documentation page for Rounded:
https://tailwindcss.com/docs/border-radius#customizing-your-theme

However no equivalent theme properties appear to be provided for the options mentioned above.

• https://tailwindcss.com/docs/border-width#using-a-custom-value
• https://tailwindcss.com/docs/box-shadow#customizing-your-theme
• https://tailwindcss.com/docs/outline-width#using-a-custom-value

Additionally I'd be specifically interested in learning how the default values can be modified for these utilities. In Tailwind v3 these used the DEFAULT name:

https://v3.tailwindcss.com/docs/border-width#customizing-your-theme

module.exports = {
  theme: {
    borderWidth: {
      DEFAULT: '1px', // <-- what's the v4 equivalent?
      '0': '0',
      '2': '2px',
      '3': '3px',
      '4': '4px',
      '6': '6px',
      '8': '8px',
    }
  }
}

[philipp-spiess]

@endigo9740 Hey! These namespaces are removed from the docs since we don't think it's a good way to use them for new v4 projects. They will still be there if you need them for backward compatibility though and are also used by our upgrade tool. For example. the border-width-* utilities will still query the --border-width-* CSS namespace even though _we don't recommend using it and instead use the spacing scale. You can find this in the source code here: https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/src/utilities.ts#L2105

[endigo9740]

Hi @philipp-spiess thanks for the response.

Sorry to respond in a closed message, but I don't know that this stance quite addresses our issue and use case. To provide some context, my name is Chris and I'm the creator and core maintainer for Skeleton. Note that we're working on a major update that will include Tailwind v4 support.

We've long since provided an opinionated structure for themes in Tailwind, by implementing CSS custom properties that are then consumed by a Tailwind plugin to generate utility classes (a basic design token system). In Tailwind v4 we're thrilled to see @theme provide a first-class solution for this. We're very keen to adopt this strategy.

Unfortunately, this does affect the properties mentioned above: border|divide|ring|outline. We generated our Tailwind v3 theme format with the assumption we could overwrite the default sizes for each of these properties, again tied to a paired CSS custom property in your theme file. Here's a minimum example:

module.exports = {
  theme: {
    borderWidth: {
      DEFAULT: `var(--border-width-default)`
    }
  }
}

But now you're telling me that not only are the namespaces values for these not documented, but DEFAULT is no longer possible to set, and Tailwind is no longer recommending folks be able to create standardized widths for these properties?

You see where I'm going with this - that the idea of standardizing these values is actually quite helpful to the context of themes. If I have an app where I have dozens of elements that utilize border-width, I don't want to set that over and over, or hope that members of my team remember follow the correct convention for width. I want to be able to draw from a single source of truth.

If I understand correctly, the recommendation is now to extend these properties with a new width utility, is that correct? Something like:

@theme {
  border-theme: var(--border-width);
  ring-theme: var(--border-width);
  outline-theme: var(--border-width);
}

Which can then be used like so:

<div class="border-theme border-red-500">

[philipp-spiess]

Hey! Yeah sorry for closing this too soon, I misunderstood your question.

If I understand correctly, the recommendation is now to extend these properties with a new width utility, is that correct?

Oh, sorry, I think you misunderstood. Our recommendation is to not configure these *-width scales at all and instead make only configure the --spacing scale. For the default, we have used 1px as it is the most common value for things like border widths and we think that if you want something different, it's better to write this into the markup itself than changing the configuration. This way someone new to the project but maybe familiar with Tailwind CSS has a much faster time to finding out what's going on.

However, it is still possible to configure these defaults for backward-compatibility. E.g. for border the value is read from the --default-border-width theme variable and can overwrite the default of 1px, e.g.: https://play.tailwindcss.com/OXPBKArulo?file=css

These defaults also exist as --default-ring-width and --default-divide-width but I just noticed that indeed it does not work for outlines so this is definitely unexpected and we'll look into this.

[chris-simmons-maingau]

Oh no worries at all @philipp-spiess, I go through a ton of issues each week so I know how it goes! :)

And thanks for the clarification and update on the defaults - that's extremely helpful. I understand outline is a bit outlier compared to the rest, given how critical it is to a11y. That's likely why it's handled separate. At this point we may just drop outline, as I really don't want Skeleton to be responsible for users mistakenly setting that to 0px for example - which would be quite harmful.

For the other properties, it's kind of nice just to have this standard that border and ring provides the theme-specified default out of the box, without having to think about it and/or learn a new convention. But we will still consider the explicit utility extension to help ensure future compatibility if the defaults might go away later.

I'd be curious to hear more about Outline, but I believe my original question has now been addressed if you wish to close this.

And just a quick thanks to you and the team for all y'all hard work on v4! We're we're already blown away by all the new features and quality of life improvements. We're going to be doing some really fun stuff with the new tools you've handed us!

[philipp-spiess]

Alright we made sure that --default-outline-width will also work with the next patch release 👍

[chris-simmons-maingau]

Awesome, thanks Philipp!