Nested color objects with mixed-case parent keys don't generate utilities in v4

[lohani-mohit]

Tailwind CSS version : v4.1.18

Build tool: Next.js 15.5.7 with @tailwindcss/postcss

Node.js version : v20.11.1

Browser: Chrome (also tested in Safari - same behavior)

OS: macOS 15.2

Issue

In Tailwind CSS v4, nested color objects in tailwind.config.ts fail to generate utility classes when the parent key contains mixed-case or alphanumeric characters (e.g., iosV3, myTheme, v3Landing). However, lowercase-only parent keys (e.g., iosv3, glass, electric) work correctly.

This behavior is undocumented and creates confusion during migration from v3 to v4, as mixed-case keys worked fine in v3.

Steps to Reproduce

1. Configuration Setup

globals.css:

@import "tailwindcss";
@config "./tailwind.config.ts";

tailwind.config.ts:

import type { Config } from "tailwindcss";

const config: Config = {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {
      colors: {
        // ❌ This DOESN'T generate utilities
        iosV3: {
          "glass-700": "rgba(26, 26, 27, 1)",
          "glass-800": "rgba(17, 17, 18, 1)",
          "electric-400": "rgba(34, 80, 225, 1)",
        },

        // ✅ This DOES generate utilities
        glass: {
          700: "rgba(31, 31, 31, 1)",
          800: "rgba(17, 17, 18, 1)",
        },

        // ✅ This DOES generate utilities
        electric: {
          400: "rgb(33, 55, 252)",
        },
      },
    },
  },
};

export default config;

2. Component Usage

// Try to use the colors
<div className="bg-iosV3-glass-700">     {/* ❌ No style applied */}
  This has no background
</div>

<div className="bg-glass-700">           {/* ✅ Works correctly */}
  This has background
</div>

<div className="bg-electric-400">        {/* ✅ Works correctly */}
  This has background
</div>

3. Build and Inspect

npm run build
# Check generated CSS - iosV3 utilities are missing

Expected Behavior

All nested color objects should generate utilities, regardless of parent key casing:

• bg-iosV3-glass-700 should be generated from iosV3: { 'glass-700': '...' }
• text-myTheme-primary should be generated from myTheme: { 'primary': '...' }
• Or at minimum, provide a clear warning/error during build

This behavior worked in Tailwind CSS v3.

Actual Behavior

• ✅ glass: { 700: '...' } → Generates bg-glass-700
• ✅ electric: { 400: '...' } → Generates bg-electric-400
• ❌ iosV3: { 'glass-700': '...' } → No utilities generated (silent failure)
• ✅ iosv3: { 'glass-700': '...' } → Generates bg-iosv3-glass-700 (lowercase works!)

Workaround

Rename all mixed-case parent keys to lowercase:

// Before (doesn't work)
colors: {
  iosV3: { 'glass-700': '...' }
}

// After (works)
colors: {
  iosv3: { 'glass-700': '...' }
}

Then update all component usages:

// Before
<div className="bg-iosV3-glass-700">

// After
<div className="bg-iosv3-glass-700">

Impact

This issue:

1. Breaks existing codebases migrating from v3 to v4 with mixed-case color keys
2. Fails silently - no errors or warnings, styles just don't apply
3. Is undocumented - not mentioned in the v4 upgrade guide or documentation
4. Creates debugging confusion - developers see classes in HTML but no styles applied

Proposed Solutions

Option 1: Support mixed-case keys (preferred)

Make Tailwind v4 handle mixed-case parent keys the same way it handles lowercase keys.

Option 2: Document the limitation

Add clear documentation to the v4 upgrade guide explaining:

• Mixed-case parent keys are not supported
• Use lowercase-only parent keys for nested color objects
• Provide migration instructions

Option 3: Show warnings

Display a build-time warning when detecting mixed-case parent keys:

⚠ Warning: Color key 'iosV3' contains mixed-case characters.
Tailwind v4 only generates utilities for lowercase parent keys.
Consider renaming to 'iosv3' for utilities to be generated.

Additional Context

We discovered this while upgrading a large production codebase. The issue affected:

• 43 component files
• Multiple color utilities (bg-, text-, border-, fill-, from-, etc.)
• Required bulk renaming across the entire codebase

The discovery process took significant debugging time because:

1. No errors were shown
2. HTML contained the correct class names
3. CSS just didn't include the utilities
4. No mention in documentation or upgrade guide

Related

• Migration guide: https://tailwindcss.com/docs/upgrade-guide
• Color configuration: https://tailwindcss.com/docs/customizing-colors

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Utility class name transforms lowercase+uppercase keys (camelCase/PascalCase) to kebab-case unexpectedly when using JavaScript config file #18114

Related Issues

• @utility won't generate some class names #17960
• JS config colors get kebab-cased while CSS config colors don't #19336
• Mapping complex design systems to tailwind utilities broken in v4 CSS config DSL #18841

🔗 Related PRs

#19337 - Don’t unconditionally convert config keys to kebab-case [merged]
#19344 - Handle future and experimental config keys during upgrade [merged]
#19348 - Improve compatibility with special default values in JS configs [merged]
#19381 - Handle backwards compatibility for content theme from JS configs [merged]
#19419 - Don’t emit color-mix fallback rules inside @keyframes [merged]

👤 Suggested Assignees

• thecrypticace
• woohm402
• sn3h
• gabrielmfern
• non25

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[thecrypticace]

Will be fixed in the next release 👍