More Explicit Upgrade Docs

[skstuder]

The conversion was tough for me and took about twice as long as I expected. I think the docs could benefit from a few more explicit callouts.

A few things that would have helped:

• Clearly explain what changed in the CSS reset. I spent days chasing a bug where a Preflight change (new in v4) was overriding a user agent style that wasn’t visible in the DOM, which caused unexpected table spacing. A diff or changelog of reset changes would be really helpful for identifying potential regressions. The docs currently just say “we made a couple changes to Preflight” and list three things, but the reset definitely contains more.
• Maybe this is lazy, but visual side-by-sides of v3 and v4 would be super helpful. For example, showing what variable overrides looked like in v3 and how that same thing is done in v4. Same with disabling Preflight. The upgrade guide is mostly text-heavy, and more visual examples would go a long way. Especially for users with a JavaScript-heavy background who may not find the new CSS module setup immediately intuitive.
• Is there a reason the upgrade tool can’t convert JS config to the new CSS module format? It seems like it could populate the @theme variables automatically, unless there’s something I’m missing that makes this difficult.
• Mention somewhere that you can associate CSS files with Tailwind in VS Code via settings. This might not be new in v4, but many users will run into this for the first time if they haven’t used Tailwind’s CSS features before:

"files.associations": {
  "*.css": "tailwindcss"
}

• Is it just me, or are there no CLI docs? I wanted to output the generated CSS so I could diff it against a previous version to track down my Preflight issue and never figured out how.

Those are my thoughts. I'm a huge fan and have converted many devs to TW. Overall, I’m happy with the new features, and I hope this feedback can help improve the docs going forward.

[miachenmtl]

I 100% agree about clarifying the Preflight css reset. I'd add that if you used the tabbed format like in the Installation section with 'Using PostCSS' / 'Using Vite' / 'Tailwind CLI', it would be more apparent that you don't need to install postcss if you're using the Vite plugin.

[codenomnom]

I'd use this issue so I don't open new one that is clearly connected. It seems different people had issues with the same issue I had - specificity in custom breakpoints. Turns out V4 sorts breakpoints (maybe other things as well?) based on their value, which was obviously not the case before (as it worked).

This causes major issues when used with combination with default breakpoints: md:basis-1/2 scr1200:basis-1/4. The default ones simply override your custom ones, as they have the same specificity, but are rendered in different order in the final CSS file. Mine use px and the default ones are rem, so they get at the end.

There was a PR for updating the docs, but I find it so buried and looking "non-important" that it doesn't actually work. It says it's important to always use the same unit for defining your breakpoints or the generated utilities may be sorted in an unexpected order. Tailwind uses `rem` for the default breakpoints (...) make sure you use `rem` as well..

This quote is within Responsive Design - Customize your theme section of the website...

It'll be really nice to heave clear documentation, especially in the migration guide!