Upgrading to Tailwind v4: Missing Defaults, Broken Dark Mode, and Config Issues

[JaquesBotha]

Introduction

Hello Tailwind CSS Team and Community,

First off, I want to say that I really appreciate all the hard work that goes into Tailwind CSS. It’s an incredible tool that has improved my workflow tremendously. However, after upgrading to v4, I’ve run into several challenges that have made the transition more difficult than expected.

I completely understand that major updates come with changes, but some of the alterations, such as the removal of default styles, changes to dark mode behavior, and unexpected issues with Tailwind config properties, were not clearly outlined in the upgrade guide. I’ve also noticed that I’m not alone in experiencing these difficulties, as other developers have expressed similar concerns.

What I've Done So Far

• Updated everything as per spec, including fixing prefixes (tw- to tw: and moving them to the front).
• Followed the official upgrade guide but found certain key changes missing from the documentation.
• Adjusted multiple UI components to work with v4, but encountered issues with default styles, dark mode, and custom config values.

Issues Faced

1. Loss of Default Styles: Previously, elements like headings and buttons had reasonable defaults. After upgrading, these defaults are gone, which caused a lot of unexpected UI issues. Also the @layer base {} thing does not work. Tried it many times now.

2. Dark Mode Behavior Changed: Dark mode does not seem to work the same way as it did in v3. If this was an intentional change, could you clarify the best practices for handling it in v4? Should that not be a change set outline in Upgrade docs?
   

3. Tailwind Config Custom Properties Not Working: Specific configurations in tailwind.config.js, such as:

   backgroundImage: {
       dots: "radial-gradient(circle, #d4d9e0 1px, transparent 1px)"
   },
   backgroundSize: {
       dots: "20px 20px" // Adjust size as needed
   },

   These settings appear in the compiled CSS but do not seem to work properly.

Dots are not showing as it did in the past!

5. List (<ul>) Padding Changes: UL elements that were previously well-spaced now have different padding, affecting layouts unexpectedly.
6. Heading Default Sizes Removed: The removal of default font sizes for headings means that all heading elements now require manual fixes across projects.
7. @layer base Behavior: Even when attempting to reintroduce styles via @layer base, they are not applying as expected.
8. Tailwind Class-Based Animations No Longer Work Properly: TypeScript animations relying on Tailwind classes (opacity-0, opacity-100, translate-y-0, etc.) do not behave the same way as before. HOWEVER, I have not fully investigaged this point just yet!

Steps Taken

• Read through the Tailwind CSS v4 Upgrade Guide but found no detailed explanation for these issues.
• Checked through discussions and issues to see if others had encountered the same problems but did not find clear resolutions.

Request for Assistance

I’d love to get some clarification on the following:

• Were the removal of default styles for elements (headings, buttons, lists, etc.) intentional? If so, what is the recommended approach for handling this in v4? Or give us the control. Tons of developers want these proper defaults, this is what makes Tailwind so great!
• What changes were made to dark mode functionality, and how should we approach implementing it moving forward?
• Why are Tailwind config properties compiling but not working as expected?
• What is the best way to reintroduce defaults that were removed in a way that is sustainable long-term?
• Are there any known issues with Tailwind-based animations behaving differently in v4? AGAIN STILL NEEED TO INVESTIGATE THIS A BIT MORE.

Conclusion

I truly appreciate all the work that has gone into Tailwind CSS and understand that updates are necessary for improvement. That said, I believe better documentation and clearer migration steps for these changes would be incredibly helpful for those of us upgrading large projects.

Looking forward to any insights you can provide, and I appreciate your time in addressing these concerns.

Best regards,
Jaques

[adamwathan]

Hey!

Previously, elements like headings and buttons had reasonable defaults.

This isn't true — headings, buttons, lists, etc. have always been completely unstyled in Tailwind. Here is a v3 demo demonstrating that:

https://play.tailwindcss.com/5DSGDzqrxj

Dark mode does not seem to work the same way as it did in v3. If this was an intentional change, could you clarify the best practices for handling it in v4? Should that not be a change set outline in Upgrade docs?

Can you explain what you mean? You haven't provided any information here about what behavior you are seeing vs. what behavior you are expecting. Dark mode is meant to work the same way as it always has, with the only notable difference being how you configure it when using a CSS-based configuration:

https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually

Tailwind Config Custom Properties Not Working

Can you provide a reproduction of this?

Even when attempting to reintroduce styles via @layer base, they are not applying as expected.

Can you provide a reproduction of this?

Tailwind Class-Based Animations No Longer Work Properly

Can you provide a reproduction of this?

---

Happy to resolve any issues if there are bugs here but we can't be much help if you don't follow the issue template and include reproductions of the issues you are facing.

[ktml]

I have encountered issue 2 where dark mode wasn't working properly.

Turned out it's because I did @import 'tailwindcss' in another css file, causing the light mode style overriding the dark mode style. I merged the css back into one file and dark mode is working fine again.

[Tonyweb72]

Its actually save my day, this information should be on dark mode page on official website @adamwathan

[sachinnsinghh]

it should be in globals.css file right?

[ktml]

@sachinnsinghh yes if globals.css is the main css file on your site

[AbdwGTK]

Legend

[thammarith]

Not sure if it's an exactly the same problem. I found that I imported incorrectly.

For me, I was doing @import '../styles/global.css'; (where it has @import "tailwindcss";) in a CSS file (BaseLayout.css). It turned out that I have to import in the component file (BaseLayout.astro) instead.

[ShobanaV]

https://stackoverflow.com/questions/79580715/the-default-classic-styling-of-html-elements-is-lost-when-i-import-tailwindcss-i

[rozsazoltan]

Yeah, and some related: The @config was created so that anyone migrating from v3 to v4 would have the option to get their app running quickly with minimal changes, but many breaking changes have occurred in the meantime, which you should review:

• Upgrade guide
• Theme variables (configuration)
• What's breaking changes from v4?
• Tailwind CSS v4: more packages and new Vite support
• How to switch to a CSS-first configuration in Tailwind CSS v4 and above

Other related:

• How to use custom color themes in TailwindCSS v4
• How to override theme variables in TailwindCSS v4 - @theme vs @layer theme vs :root
• Should I use @theme or @theme inline?
• When should I use * and when should I use :root, :host as the parent selector?
• backgroundImage in CSS-first configuration