Tailwind v3 preflight conflicts with Tailwind v4 preflight (border/margin/padding utilities broken)

[amh6281]

Hi Tailwind team 👋

I'm facing a compatibility issue when importing a precompiled design system built with Tailwind v3 into a project using Tailwind v4.

Setup

• App uses Tailwind v4
• Imported package CSS (built with v3) includes its own @tailwind base

// App.tsx
import 'design-system/dist/assets/style.css';

Problem

Once imported, several Tailwind v4 utilities stop working properly — e.g.:

// Test.tsx
<div class="border border-red-500 pl-4 mr-4">test</div>

• border-color appears as neutral instead of red-500
• m- / p- utilities behave inconsistently

Cause

Tailwind v3 preflight sets global border defaults:

*, ::before, ::after {
  border-width: 0;
  border-style: solid;
  border-color: #e5e7eb;
}

Tailwind v4’s preflight, however, resets borders differently:

*, ::after, ::before {
  border: 0 solid;
  margin: 0;
  padding: 0;
}

The v3 preflight overrides v4’s expectations, breaking CSS variable–based utilities like border-red-500.

Temporary workaround

As a temporary fix, I’m using the following override to revert the v3 preflight impact:

// index.css (my_project)
*:not(svg):not(svg *) {
  border: revert-layer;
  margin: revert-layer;
  padding: revert-layer;
}

This restores most v4 utility behavior, but it’s not ideal or sustainable.

Questions

• Is there a recommended way to coexist a precompiled Tailwind v3 CSS with Tailwind v4 without editing the package?
• Would disabling preflight in the design system (corePlugins.preflight = false) be a safe solution?
• Are there best practices for scoping or isolating compiled Tailwind CSS (e.g. layer scoping, prefixes, shadow DOM, import order)?
• Is there any migration guidance or compatibility layer for legacy Tailwind builds?

Thanks for your time and guidance 🙏

[KaloudasDev]

Hello! This is a known compatibility issue when mixing Tailwind v3 and v4 preflight styles. Here are the recommended solutions:

Solution 1: Disable Preflight in v3 Design System
In your design system's tailwind.config.js:

module.exports = {
  corePlugins: {
    preflight: false,
  },
}

Solution 2: Use CSS Layer Scoping
Wrap your design system styles in a dedicated layer:

/* In your design system's main CSS file */
@layer design-system {
  /* Your component styles here */
  .btn { /* ... */ }
  .card { /* ... */ }
}

/* Remove @tailwind base from design system CSS */

Solution 3: Build Design System Without Base Styles
When building your design system, exclude base styles:

// Design system build configuration
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  corePlugins: {
    preflight: false, // Critical: disable preflight
  },
  plugins: [
    // Your plugins
  ],
}

Solution 4: CSS Import Order Management
In your main application, control import order:

/* app.css */
@import "tailwindcss"; /* v4 first */
@import "design-system/dist/assets/style.css"; /* v3 components after */

Solution 5: Enhanced Workaround with Layer Isolation

/* In your main app CSS */
@layer base {
  /* Reset v3 border conflicts */
  *:not(.design-system *):not(svg):not(svg *) {
    border-color: inherit;
    border-style: inherit;
    border-width: inherit;
  }
}

/* Import design system after base reset */
@import "design-system/dist/assets/style.css";

Solution 6: Build-Time Component Isolation
For your design system build process, use PostCSS to scope styles:

// postcss.config.js for design system
module.exports = {
  plugins: [
    require('postcss-prefix-selector')({
      prefix: '.design-system',
      transform: function (prefix, selector, prefixedSelector) {
        if (selector.includes('html') || selector.includes('body')) {
          return selector;
        }
        return prefixedSelector;
      },
    }),
  ],
}

Recommended Approach:
The most sustainable solution is Solution 1 - rebuilding your design system with preflight: false. This ensures compatibility and follows Tailwind's recommended approach for component libraries.

If you cannot modify the design system, Solution 4 with careful import ordering combined with Solution 5 for conflict resolution provides the best temporary fix.