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.