[docs] Properly indicate Tailwind version

[Studio384]

Docs feedback

How can we improve Base UI documentation?

The Tailwind examples in the documentation are built with Tailwind 4. As far as I can tell, this isn't noted anywhere. Copying the examples in many cases will result in inconsistencies between the example and the pasted result in any project that doesn't use Tailwind 4 (which I'd assume is the vast majority of them right now) due to the changes to some defaults (e.g. dialogs have a bigger outline).

As long as Tailwind 4 isn't the current version, it is probably worth indicating somewhere that the examples are assuming the use of v4. I'd suggest just changing the text in the style dropdown from "Tailwind CSS" to "Tailwind CSS v4".

[colmtuite]

@vladmoroz Perhaps just change the select option to "Tailwind v4"?

[vladmoroz]

I'll fix the outlines. Other than the outlines, is there another example that looks really different in v3 and v4?

We haven't used any of the v4-only features. The styles we used should be all backwards compatible with v3. If not, we should treat it as a bug to fix.

I don't want to include an indication of v4 because many folks will stay on v3 for a long time, and they are largely the same apart a few defaults.

[Studio384]

There is quite a bit of rounded-sm in the examples, so people copying (e.g.) the checkbox examples will get a more square-ish design.

The examples being rendered with Tailwind v4 but being written with v3's syntax and classes is a strange choice in my opinion. It took me quite some time to figure out if I configured something incorrectly in my project before I decided to just check the code of the docs to see which Tailwind version was being used. Then there's the discrepancy that opening the examples in CodeSandbox results in them rendering with Tailwind v3.

Why are the docs using Tailwind v4 if they are written for v3?

[github-actions[bot]]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue. Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.

[!NOTE] @Studio384 How did we do? Your experience with our support team matters to us. If you have a moment, please share your thoughts in this short Support Satisfaction survey.

[vladmoroz]

There is quite a bit of rounded-sm in the examples, so people copying (e.g.) the checkbox examples will get a more square-ish design.

The examples being rendered with Tailwind v4 but being written with v3's syntax and classes is a strange choice in my opinion. It took me quite some time to figure out if I configured something incorrectly in my project before I decided to just check the code of the docs to see which Tailwind version was being used. Then there's the discrepancy that opening the examples in CodeSandbox results in them rendering with Tailwind v3.

Why are the docs using Tailwind v4 if they are written for v3?

I've updated the examples to avoid the few bits of syntax that diverge between v3/v4. There was a few bad bugs, like with Dialog positioning and missing animations that this fixed.

Since v4 is pretty much out and is slated to become the new standard within 6-9 months, we don't have much choice but to use backwards-compatible classes until we can realistically ignore v3. (And there's not that many differences to keep in mind).

We can't go full-on v4 yet because at the moment there's two immovable obstacles:

• v4 can't be used in CodeSandbox because there's no Tailwind v4 for the browser runtime yet (and API-generated sandboxes don't have a server runtime)
• v4 is just starting to gain traction. It's good enough for a new project, but might be not safe to migrate an established app from v3.

Small cosmetic differences like whether the corner rounding is 2px or 4px don't matter—when v4 for the browser is out, we'll update CSB links to use v4 and this will be resolved.