Component Library with Tailwind v4 Custom Layers Being Overridden by Project's Tailwind v3

[kowalczyk-mateusz]

Problem

I'm building a component library using Tailwind v4 that needs to be consumed by projects using Tailwind v3.4.17. I've implemented custom CSS layers to prevent conflicts, but the library's component styles are being overridden by the project's utility classes.

Library Setup (Tailwind v4)

Rollup Configuration:

rollupOptions: {
  external: ["react", "react/jsx-runtime", "react-dom", "tailwindcss"],
  output: {
    globals: {
      react: "React",
      "react/jsx-runtime": "react/jsx-runtime",
      "react-dom": "ReactDOM",
      tailwindcss: "tailwindcss",
    },
  },
}

Library CSS (main.css):

@layer theme, custom-base, custom-components, custom-utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(custom-base);
@import "tailwindcss/utilities.css" layer(custom-utilities);

/* Component styles */
@layer custom-components {
  .my-button {
    @apply bg-primary text-primary-foreground px-4 py-2 rounded-md;
  }
}

Consuming Project Setup (Tailwind v3.4.17)

Tailwind Config:

module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Include library components
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Project CSS:

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Added library source */
@source "../../node_modules/@name/components-library";

Issue

The library's component styles are being overridden by utility classes. In browser dev tools, I can see:

Expected behavior

Library component styles should take precedence over project's utility classes.

Actual behavior:

Project's utility classes are overriding library's component styles due to layer ordering.

Questions

1. How should I structure CSS layers to ensure my library's component styles have higher priority than the consuming project's utilities?
2. Is the ⁠@source approach correct for including a Tailwind v4 library in a Tailwind v3 project?

Environment

Library: React 19, Vite 7, Tailwind v4, PostCSS

Project: Next.js 15, React 19, Tailwind v3.4.17