Improve compatibility with special default values in JS configs

[thecrypticace]

Fixes #19345

In v3 the ringColor.DEFAULT option was used as the default color for ring utilities (when it was defined). This currently gets translated as --ring-color but that doesn't work this way in v4. Instead it should translate to --default-ring-color and not --ring-color.

I've also tweaked the upgrade tool to handle this properly as well.

[coderabbitai]

Walkthrough

Adds handling for DEFAULT theme keys (e.g., ringColor.DEFAULT) so they map to --default-<name> CSS variables (example: --default-ring-color). Introduces SPECIAL_DEFAULT_KEYS and OLD_TO_NEW_NAMESPACE mappings in the key-to-CSS-property logic and skips legacy container processing. Updates tests and changelog to reflect new defaults. Changes the codemod to emit an initial namespace reset only when a computed property exists, the key is not default--prefixed, and the namespace has not yet been reset.

Pre-merge checks

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is directly related to the changeset, explaining the issue, the v3 vs v4 behavior difference, and the upgrade tool fix.
Linked Issues check	✅ Passed	The PR successfully addresses #19345 by implementing the required migration of ringColor.DEFAULT to --default-ring-color in both the main config handler and upgrade tool.
Out of Scope Changes check	✅ Passed	All changes are directly related to handling ringColor.DEFAULT translation and migration; no unrelated modifications are present in the changeset.
Title check	✅ Passed	The PR title clearly and specifically describes the main change: improving compatibility with special default values (like ringColor.DEFAULT) in JS configs.

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts (1)

240-246: Migration of ringColor.DEFAULT to --default-ring-color looks correct

The upgrade path now emits --default-ring-color for ringColor.DEFAULT and skips the generic keyPathToCssProperty mapping, keeping the generated CSS consistent with the runtime theme behavior and avoiding an incorrect --ring-color variable.

If we add more special-cased theme keys in future, consider centralizing this mapping so apply-config-to-theme and the upgrader can’t drift apart.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 479b725 and 301ef64.

📒 Files selected for processing (5)

• CHANGELOG.md (1 hunks)
• integrations/upgrade/js-config.test.ts (2 hunks)
• packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts (1 hunks)
• packages/tailwindcss/src/compat/apply-config-to-theme.test.ts (2 hunks)
• packages/tailwindcss/src/compat/apply-config-to-theme.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

packages/@tailwindcss-upgrade/src/codemods/config/migrate-js-config.ts (1)

packages/tailwindcss/src/utils/escape.ts (1)

• escape (2-73)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Linux / upgrade
• GitHub Check: Linux / vite
• GitHub Check: Linux / postcss
• GitHub Check: Linux

🔇 Additional comments (5)

CHANGELOG.md (1)

18-18: Changelog entry correctly describes the ringColor.DEFAULT fix

The new “Fixed” bullet is accurate, scoped, and links to the correct PR, so the release notes will clearly communicate this behavior change.

packages/tailwindcss/src/compat/apply-config-to-theme.ts (1)

53-63: Special-case for ringColor.DEFAULT → --default-ring-color is correct and consistent

Handling ringColor.DEFAULT before the generic keyPathToCssProperty path ensures we no longer emit --ring-color and instead populate --default-ring-color with the right theme options, matching the intended v3-compatible behavior.

packages/tailwindcss/src/compat/apply-config-to-theme.test.ts (1)

60-63: Tests accurately cover the new default ring color behavior

Adding ringColor.DEFAULT to the test config and asserting that --ring-color is unset while --default-ring-color is '#fff' validates the new mapping end-to-end and guards against regressions.

Also applies to: 132-133

integrations/upgrade/js-config.test.ts (2)

37-39: LGTM! Test input properly configured.

The ringColor.DEFAULT configuration correctly sets up the test case for validating the v3 to v4 migration behavior. The test value #c0ffee is clearly identifiable in the output.

---

197-198: LGTM! Expected output correctly validates the migration.

The test properly verifies that ringColor.DEFAULT migrates to --default-ring-color (not --ring-color), which aligns with the PR objectives. The snapshot-based assertion implicitly confirms that the old --ring-color variable does not appear in the output.

[philipp-spiess]

I'm a bit confused why this is handled in isolation here since we had a lot of other DEFAULT special keys that are supported in v4 too via the --default-* pattern, e.g.: --default-ring-width, --default-outline-width, --default-transition-duration. So I'd expect there to a code path a bit more generic to handle all of these variants.

From my quick look it seems that we didn't handle this in apply-config-to-theme at all right now so not sure if this is an oversight or if there's an alternative explanation?

[thecrypticace]

Yeah this is a good point. We do handle a few default things with regards to fonts but nothing else. Lemme do a bit of poking around to see if we need to handle a few more things.