Skip to content

Conversation

@Yeom-JinHo
Copy link

Description

This PR focuses on fixing incorrect arbitrary utility conversions introduced during the Tailwind v4 migration.
Some utilities using CSS variables like gap-[var(--gap)] were mistakenly transformed into gap-(--gap) by the upgrade CLI, causing runtime and style mismatches.
This update restores proper handling for CSS variable–based arbitrary values to ensure accurate conversion and consistent styling.


Changes

  • Early Guard for Complex Arbitrary Values

    • In arbitraryUtilities, when the candidate is functional + arbitrary, conversion is skipped if the raw value contains var(), calc(), spaces, commas, or slashes.
    • Prevents invalid rewrites such as gap-[var(--gap)]gap-(--gap).
  • String Normalization

    • Normalize the raw value to valueStr = String(value) for consistent parsing and formatting.
  • Complex Value Handling

    • If isComplex is true, do not attempt bare-value replacements; only emit the bracketed arbitrary form (${root}-[${valueStr}]).
  • Modifier Serialization

    • Use printModifier() when emitting classes with modifiers to ensure correct formatting.
  • Storage/Signature Access (No Behavior Change)

    • Read precomputed utilities and signatures via designSystem.storage[PRE_COMPUTED_UTILITIES_KEY | UTILITY_SIGNATURE_KEY].get(options.signatureOptions).
    • Read spacing map via designSystem.storage[SPACING_KEY].

Motivation

The Tailwind v4 migration tool (@tailwindcss/upgrade) introduced incorrect transformations for arbitrary utilities using CSS variables, leading to broken layouts.
This fix ensures the migration process safely ignores complex or variable-based values and preserves valid classnames for reliable build output.


Breaking Changes

None.
This patch only restores correct handling for arbitrary utility parsing during the migration process.


Before/After

Before
gap-[var(--gap)]gap-(--gap) (invalid, broken animation/layout)

After
gap-[var(--gap)] remains intact and functional across builds

@Yeom-JinHo Yeom-JinHo requested a review from a team as a code owner October 23, 2025 14:48
@Yeom-JinHo Yeom-JinHo closed this Oct 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant