Using the <alpha-value> of config file in TW4

[cloudrendr]

To my follow Tailwinders, please assist:

When upgrading to Tailwind 4, is it possible to use a equivalent as used in the tailwind.config file, in the definition of custom color CSS variables in the main CSS file where Tailwind is imported?

Since is a config file construct, how is it supported in TW4? Or do you need still need a config file for such cases?

Some insights will be greatly appreciated.

[wongjn]

You don't need <alpha-value> at all in v4 - it can apply alpha-channel modifications whatever the color value.

[desiprisg]

How would you do the following:
oklch(from hsla(var(--foreground) / 0.05) l c h / calc(alpha * <alpha-value>))

[RobinMalfait]

As @wongjn mentioned, you don't need it. In this case you probably just want 100%, or omit the alpha value entirely oklch(from hsla(var(--foreground) / 0.05) l c h);. If you later use text-foo/50 we will wrap this value in

color-mix(in oklab, the-color-goes-here 20%, transparent);

Here is a Tailwind Play example: https://play.tailwindcss.com/K25Yr5hGeQ?file=css
The following CSS will be generated:

.bg-foo {
  background-color: var(--color-foo);
}
.bg-foo\/50 {
  background-color: color-mix(in srgb, oklch(from hsla(var(--foreground) / 0.05) l c h) 50%, transparent);
  @supports (color: color-mix(in lab, red, red)) {
    background-color: color-mix(in oklab, var(--color-foo) 50%, transparent);
  }
}

[desiprisg]

This just worked: --color-accent: hsl(var(--foreground) / 0.03);
nice! I tested the wrong element by mistake and thought it wasn't. Much simpler!

[frenzymind]

@wongjn What if I want use utility for my color, how can I achieve setting alpha value in this case?

https://play.tailwindcss.com/0GxxQZylz1?file=css

When I apply /50 I get black text. No generated css hint, so it breaks tw.

[wongjn]

You can use the built-in text-* utility by registering contrast as a color theme token: https://play.tailwindcss.com/bPoQL9ATGW?file=css

Or if you really wanted your own utility here, you can use --value(): https://play.tailwindcss.com/clGUpm6u7f?file=css

Or if you really wanted to have the /50 syntax, you'd need a fake --value():https://play.tailwindcss.com/dVL7dLNsnB?file=css

[7iomka]

Hi everyone.
@wongjn, @RobinMalfait
I’m currently migrating a project to Tailwind v4 and integrating it with PrimeNG (via tailwindcss-primeui). I’ve run into a critical architectural issue regarding how v4 handles color opacity, which completely breaks support for older browsers and creates a frustrating Developer Experience (DX).

Important Context: While the example below specifically uses PrimeNG, this is a systemic architectural issue. It affects any UI library or custom design system (including shadcn/ui and others) that maps primitive CSS color variables to semantic variables and relies on the slash syntax (/alpha) for opacity. In all these cases, the v4 engine forces a color-mix() generation where the fallback is simply the raw, un-modified solid color. Rather than computing a safe fallback from the primitive channels, it breaks UI readability and backward compatibility entirely for browsers lacking color-mix support.

The Problem

In Tailwind v4, whenever I use the slash syntax for opacity (e.g., bg-primary-500/10), the engine automatically generates a color-mix() rule:

@supports (color: color-mix(in lab, red, red)) {
  .bg-primary-500\/10 {
    background-color: color-mix(in oklab, var(--p-primary-500) 10%, transparent);
  }
}

Because color-mix() is relatively new (supported only in browsers post-early 2023), the fallback becomes just background-color: var(--p-primary-500).
For a public e-commerce project where legacy browser support (especially older iOS devices) is still required, this is a critical failure. The text color (which might also be primary-500) blends completely with the solid fallback background, making the UI unreadable.

Context & Attempted Solutions

I am trying to maintain a workflow where:

1. Raw HSL channels are my Single Source of Truth in styles.css.
2. PrimeNG consumes these channels for its internal components.
3. Tailwind v4 uses these channels for utility classes in HTML.

I want to write bg-primary-500/10 and get the v3-style output: hsl(var(--hsl-primary-500) / 0.1).

Here is what I’ve tried to bypass color-mix():

Attempt 1: Using <alpha-value> in tailwind.config.ts

I tried using the legacy JS config as an "escape hatch" to force the old compilation method:

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          500: 'hsl(var(--hsl-primary-500) / <alpha-value>)',
        },
      },
    },
  },
} satisfies Config;

Result: Failed.
Because I am importing the @import 'tailwindcss-primeui'; plugin in my CSS, the plugin generates its own @theme variables (e.g., --color-primary-500: var(--p-primary-500)). In v4, the @theme directive in CSS takes absolute precedence and overwrites my tailwind.config.ts. The slash syntax still generates color-mix().

Attempt 2: Overriding via @theme inline in CSS

I tried overriding the plugin directly in my CSS using the inline directive, hoping it would respect the <alpha-value> syntax:

@import 'tailwindcss';
@import 'tailwindcss-primeui';

@theme inline {
  --color-primary-500: hsl(var(--hsl-primary-500) / <alpha-value>);
}

Result: Failed.
The v4 CSS parser does not support <alpha-value>. It outputs the string exactly as written, resulting in invalid CSS in the browser (background-color: hsl(... / <alpha-value>)).

The Current "Ugly" Workarounds

To avoid color-mix(), I am currently forced to do Hardcode custom utilities:
Manually write @utility bg-primary-500-a10 { background-color: hsl(...) } in CSS, completely abandoning the convenient / slash syntax.

The Question

Is there an intentional, supported way in Tailwind v4 to opt-out of color-mix() generation when using the slash syntax / with dynamic variables, specifically when integrating with 3rd-party plugins that define those variables?

Forcing color-mix() as the only way to handle dynamic variable opacity seems like a massive step back for backward compatibility, especially when the developer is providing raw HSL channels that could easily support the hsl(var(--x) / alpha) syntax.

Any insights or recommended patterns for this specific architectural clash would be highly appreciated.

[wongjn]

There's no intentional supported way to opt out of color-mix() syntax in v4 that I'm aware of. The docs do indeed state that v4 is targeted at more modern browsers. I've seen the maintainers here and there recommend sticking to v3 if you need more legacy browser support.

[RobinMalfait]

As @wongjn mentioned, Tailwind CSS v4 does rely on newer browsers on purpose to make use of these new features. If this color-mix issue is the only issue right now for you, and you do want to use Tailwind CSS v4, then you can create custom utilities if you want. For example:

@theme {
  --hsl-primary-500: 0 80% 50%;
}

@utility bg-* {
  background-color: hsl(--value(--hsl-*) / calc(--modifier(integer, --default(100)) * 1%));
}

To break things down:

• --value(--hsl-*) — this means that we read from the --hsl-* namespace in your @theme blocks
• --modifier(integer, --default(100)) — means that a modifier like /50 can be used, and if it's not provided a default of 100 is used.
• calc(--modifier(integer, --default(100)) * 1%) — if you wrap that in a calc(…) then you can convert the raw number into a percentage by multiplying it by 1%. You can also use / 100 because hsl supports values like 0.7.

This way you can still use the individual channels in the --hsl-primary-500 definitions.
This eventually generates:

.bg-primary-500 {
  background-color: hsl(var(--hsl-primary-500) / calc(100 * 1%));
}
.bg-primary-500\/25 {
  background-color: hsl(var(--hsl-primary-500) / calc(25 * 1%));
}
.bg-primary-500\/50 {
  background-color: hsl(var(--hsl-primary-500) / calc(50 * 1%));
}
.bg-primary-500\/75 {
  background-color: hsl(var(--hsl-primary-500) / calc(75 * 1%));
}

So no special color-mix values in this scenario. Tailwind Play: https://play.tailwindcss.com/smlNANLPAE?file=css

Do check if you don't run into other issues since we rely on modern features. If you do, you might be better of staying on Tailwind CSS v3.

[7iomka]

So no special color-mix values in this scenario. Tailwind Play: https://play.tailwindcss.com/smlNANLPAE?file=css

Do check if you don't run into other issues since we rely on modern features. If you do, you might be better of staying on Tailwind CSS v3.

Thank you
I updated to the latest version last night and got roughly the same result.
However, overriding all the utilities could break your code if you’re using vendors that utilize or extend the Tailwind palettes.
To ensure everything works, you need to make sure that absolutely all palette colors (which will hypothetically be used in the project) are defined in the —hsl-xxx variable in the theme.

To avoid doing that, I approached it from a different angle:
I've reviewed the semantic colors for the project, and for each one I need to do something like this (for primary in ex.):

@utility bg-primary-* {
  background: hsl(--value(--hsl-primary-*) / calc(--modifier(integer, --default(100)) * 1%));
}
@utility text-primary-* {
  color: hsl(--value(--hsl-primary-*) / calc(--modifier(integer, --default(100)) * 1%));
}
@utility shadow-primary-* {
  --tw-shadow-color: hsl(--value(--hsl-primary-*) / calc(--modifier(integer, --default(100)) * 1%));
}
@utility border-primary-* {
  border-color: hsl(--value(--hsl-primary-*) / calc(--modifier(integer, --default(100)) * 1%));
}
@utility divide-primary-* {
  :where(& > :not(:last-child)) {
    border-color: hsl(--value(--hsl-primary-*) / calc(--modifier(integer, --default(100)) * 1%));
  }
}
@utility ring-primary-* {
  --tw-ring-color: hsl(--value(--hsl-primary-*) / calc(--modifier(integer, --default(100)) * 1%));
}

Besides, I'm not sure what the full list of utility attributes needs to be to cover all of Tailwind's color utilities.
There's no way to declare a single construct that would automatically create utilities wherever color is needed (like theme --color-xxx variable does under the hood). That's frustrating and inconvenient.

Any ideas?

[RobinMalfait]

You might be able to write a custom PostCSS plugin that updates the color-mix(…) usages to something that you would expect. Unfortunately you are the only person that knows what browsers to support and what classes you are using so it's either a manual job of converting these utilities to something you wrote above, or some more automatic way by creating a plugin that post-processes the CSS.

That said, since you need to support older browsers, I would recommend to stick with Tailwind CSS v3 (per the upgrade guide https://tailwindcss.com/docs/upgrade-guide) because we rely on other features like @property and @layer` as well. Once you know you can use these features, then you can upgrade.

Sorry for the inconvenience.

[7iomka]

Sorry for the inconvenience.

We have already built our project on Tailwind v4, and rolling back to v3 isn't a viable option for us. We really appreciate the v4 ecosystem, the utilities, and the overall developer experience. We want to keep moving forward with it.

However, we are running into a significant issue when Tailwind fails to resolve the value of a CSS variable—especially when dealing with semantic variables that reference base variables.

The most critical pain point isn't just the resolution failure itself, but how the fallback is applied. Tailwind currently sets the fallback to a "flat" (fully opaque) color value.

The Problem

In our UI, we frequently use a pattern where the background is set to a transparent version of the text color (e.g., 20% opacity of the text color).
Because Tailwind injects a fully opaque fallback, browsers that do not support the modern syntax end up applying the solid fallback color to the background. As a result, the text completely blends into the background, making it invisible.

The Impact

Because of this behavior, we are forced to write messy workarounds and crutches just to keep our UI accessible in older environments.
For most of unsupported features we have possibility to use wellknown postcss plugins , but not for this specific case.

Proposed Solution

We want to stay up-to-date with Tailwind v4, but we strongly need a way to prevent it from injecting these opaque fallbacks. Currently, there seems to be no way to opt-out of this fallback generation.

Could we get a configuration option (or make it opt-in/opt-out) to disable these color fallbacks?
Or somehow to get a way to configure / specify exactly how it should be generated?
This would give us back the control we need to handle legacy browser support gracefully without breaking our UI.

In any case, thanks for the advice. I realize this is more of a feature request, which probably isn't of much interest to the library's developers.

[JulyanXu]

Short version: I don't think there is a supported v4 equivalent of <alpha-value> inside @theme, and I don't think there is currently a supported opt-out that makes normal slash opacity generate hsl(var(--x) / alpha) instead of color-mix().

Looking at the v4 source, opacity modifiers are centralized through withAlpha() and that function returns:

color-mix(in oklab, <value> <alpha>, transparent)

Also, the compatibility path that imports JS config values replaces <alpha-value> with 1, so it is not a live placeholder in v4 CSS theme variables.

So for your PrimeNG / older-browser case, the practical choices are basically:

1. Keep using Tailwind's slash syntax and accept the color-mix() requirement.
2. For legacy-safe surfaces, use explicit arbitrary values where needed, for example:

<div class="bg-[hsl(var(--hsl-primary-500)_/_0.1)]"></div>

3. Define named custom utilities for the alpha steps you actually use:

@utility bg-primary-500-a10 {
  background-color: hsl(var(--hsl-primary-500) / 0.1);
}

@utility text-primary-500-a80 {
  color: hsl(var(--hsl-primary-500) / 0.8);
}

4. Add your own @supports not (color: color-mix(in oklab, red, transparent)) fallbacks for the generated utilities, but that can get ugly quickly because you have to mirror every opacity variant you rely on.

So your "ugly workaround" is unfortunately close to the current supported escape hatch if legacy browsers matter. If the goal is to preserve v3-style channel variables with /alpha, the best API would likely need to come from Tailwind core or from tailwindcss-primeui exposing legacy-safe utilities/channel tokens explicitly.