TailwindCSS v4 does not recognize some colors

[androide-osorio]

Description

Hello,

At my company, we use TailwindCSS to build and maintain the component libraries that make our design system. We are currently migrating our Tailwind 3.4.10 Tailwind 4.1.0, and I have encountered a puzzling issue.

We are generating a custom theme with a prefix, based on the design system's design tokens using style dictionary. We divide colors in primitive and semantic tokens, the latter ones just are a reference to the first ones. The output looks something similar to this:

@import "tailwindcss" prefix(uy);
@import "@fontsource/inter";

@theme inline static {
  --color-*: initial;
  --color-grayscale-L1: oklch(99.059% 0.0017 247.84);
  --color-grayscale-L2: oklch(98.22% 0.00412 271.37);
  --color-grayscale-L3: oklch(96.001% 0.00625 255.48);
  --color-surface-neutral: var(--uy-color-grayscale-L2); /* this color references another variable */
  /* More colors and variables... */
}

Expected behavior

Expected class names like uy:bg-grayscale-L1, uy:bg-grayscale-L2, ... uy:bg-surface-neutral to be generated and to apply the styles.

<div class="uy:bg-grayscale-L2" /> // background-color: var(--uy-color-grayscale-L2)
<div class="uy:bg-surface-neutral" /> // background-color: var(--uy-color-surface-neutral)

Actual behavior

The classes for the primitive tokens are not generated, but the classes for the semantic tokens do get generated.

<div class="uy:bg-grayscale-L2" /> // ❌ doesn't work, class not generated
<div class="uy:bg-surface-neutral" /> // ✅ works, class generated

In the screenshot above, that element should be almost black. The other elements beside it render colors correctly because they use the semantic classes (tokens that are aliases of the of colors in the color palette)

What I find most puzzling is that, when I add the theme into Tailwind Play, everything works correctly: https://play.tailwindcss.com/3BGP0eYX8t, which means it is not a theme configuration issue.

Environment setup

The project is an Nx Monorepo, containing the component library, in this fashion:

<root>
|_ packages
  |_ design-system
    |_ components // consumes the theme css file
    |_ themes // exports the theme css file

the themes package exports the generated css file as its default export:

"exports": {
    ".": {
      "default": "./dist/css/theme.css"
    },
    "./dist/css/theme.css": "./dist/css/theme.css"
  },

The component project itself uses Vite for bundling the library and Storybook as the testing platform.

// vite.config.ts
/// <reference types='vitest' />
import tailwindcss from '@tailwindcss/vite'

// Custom config if needed. Use this only if you have a strong need
// to customize the config.
// Please document why if you need to change something
export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

And in .storybook folder, we just have a stylesheet that imports the theme css file:

/*components/.storybook/styles.css*/
@import '@myorg/designsystem-themes';

// preview.tsx
import './styles.css'

// more code configuring storybook...

Package versions

These are the (abbreviated) package dependencies.

{
  "name": "@myorg/designsystem-components",
  "dependencies": {
    "react": "18.3.1",
    "react-dom": "18.3.1",
    "tailwind-merge": "2.5.2",
    "tailwind-variants": "1.0.0",
  },
  "devDependencies": {
    "@fontsource/inter": "5.0.19",
    "@fontsource/source-serif-4": "5.0.19",
    "@storybook/addon-a11y": "9.1.0",
    "@storybook/addon-docs": "9.1.0",
    "@storybook/addon-links": "9.1.0",
    "@storybook/addon-vitest": "9.1.0",
    "@storybook/react-vite": "9.1.0",
    "@types/react": "18.3.18",
    "@types/react-dom": "18.3.5",
    "@types/react-router-dom": "5.3.3",
    "@vitejs/plugin-react": "4.7.0",
    "@vitest/browser": "3.2.4",
    "storybook": "9.1.0",
    "tailwindcss": "4.1.0",
    "typescript": "5.7.3",
    "vite": "6.3.5",
    "vite-plugin-node-polyfills": "0.23.0",
    "vitest": "3.2.4"
  },
}

---

any help you can provide would be greatly appreciated.