Unknown utility class issue in a Phoenix application when upgrading from Tailwindcss v3.3 to v4.1

[saleyn]

After upgrading from Tailwindcss v3.3 to v4.1, I am getting the following error:

$ mix assets.build
...
Generated utilx app
Error: Cannot apply unknown utility class: checked:border-brand-500

The assets/css/app.css contains:

@import "tailwindcss";
@import "../../deps/utilx/assets/css/inputs.css";

And inputs.css has a reference to checked:border-brand-500.

In the Tailwind 4.x upgrade guide they recommend using the @reference /path/to/app.css in the imported file. However, including such a reference in inputs.css results in two problems:

A circular dependency (app.css → inputs.css → app.css)

$ mix assets.build
Error: Exceeded maximum recursion depth while resolving `./theme.css` in `/$bunfs/root`)
From the design point of view it’s unclear why the stand-alone dependency application should reference another (parent) application’s css.

Could you please clarify how to make an upgrade so that custom colors and other classes used in the @apply function in the inputs.css work correctly in v4.1?

[wongjn]

Consider checking border-brand-500 would exist as a class:

 @import "tailwindcss";
 @import "../../deps/utilx/assets/css/inputs.css";
+
+@theme {
+  --color-brand-500: red;
+}

[saleyn]

I have the following section in the tailwind.config.json:

const colors = require("tailwindcss/colors");

module.exports = {
  ...
  theme: {
    extend: {
      ...
      colors: {
        brand:   colors.blue,
        danger:  colors.red,
        warning: colors.yellow,
        info:    colors.sky,
        ...
      },
    },
    ...
  }
}

@wongjn, if I remove this and define in the app.css as you suggested, do I need to do it just for the "top-level" color names (e.g. --color-brand) or all numeric variants as well (i.e. --color-brand-50, --color-brand-100, ...)?

If references to color-brand-* are in the app.css and input.css do I need to define it in theme.css and use @reference to reference it in each file? E.g.:

*app.css:*

@import "tailwindcss";
@reference "./theme.css";
@import "../../deps/utilx/assets/css/inputs.css";

*inputs.css:*

@reference "../../deps/my-main-app/assets/css/theme.css";
...

[wongjn]

if I remove this and define in the app.css as you suggested, do I need to do it just for the "top-level" color names (e.g. --color-brand) or all numeric variants as well (i.e. --color-brand-50, --color-brand-100, ...)?

You'd need to do it for all numeric variants.

If references to color-brand-* are in the app.css and input.css do I need to define it in theme.css and use @reference to reference it in each file?

If app.css @imports all the CSS files used in your project, consider defining the @theme in app.css. The other CSS files that app.css @imports do not need to @reference anything then.

Otherwise, if you define @theme in theme.css, @import it in app.css. Any CSS files that app.css @imports do not need to reference theme.css. Any other CSS files that are in a separate CSS "pipeline" to app.css would need to reference theme.css.

In either situation, it looks like to me you wouldn't need to @reference anything in inputs.css.

[saleyn]

Thank you!

One more question: I have the following that used to work in 3.x:

.uc-label-select {
  @apply absolute text-sm text-gray-500 dark:text-gray-400
}

.uc-label {
  @apply uc-label-select -translate-y-5 scale-75 whitespace-nowrap;
}

Is it no longer possible to apply classes such as uc-label-select like this in 4.x?

[wongjn]

You'd need to register uc-label-select as a utility class:

-.uc-label-select {
+@utility uc-label-select {
   @apply absolute text-sm text-gray-500 dark:text-gray-400
 }

[saleyn]

Thanks a bunch! Your responsiveness is truly amazing! ;)