From 95b82ddb79b96affa8538aa271833fc4f547a410 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Thu, 9 Oct 2025 22:18:34 +0200
Subject: [PATCH 1/7] canonicalize units
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We will normalize units to their canonical form, this is an initial step
for allowing `rem` to `px` conversion as well.

in, cm, mm, q, pc, pt   → px
grad, rad, turn         → deg
ms                      → s
khz                     → hz

Already provided the option to pass in a `rem` value. Once passed in, we
will convert `rem` to `px` as well.
---
 .../src/constant-fold-declaration.test.ts     | 12 ++--
 .../src/constant-fold-declaration.ts          | 70 +++++++++++++------
 2 files changed, 53 insertions(+), 29 deletions(-)

diff --git a/packages/tailwindcss/src/constant-fold-declaration.test.ts b/packages/tailwindcss/src/constant-fold-declaration.test.ts
index 1fdbbde81402..b95ed74a340b 100644
--- a/packages/tailwindcss/src/constant-fold-declaration.test.ts
+++ b/packages/tailwindcss/src/constant-fold-declaration.test.ts
@@ -72,18 +72,18 @@ it.each([
 
 it.each([
   ['0deg', '0deg'],
-  ['0rad', '0rad'],
+  ['0rad', '0deg'],
   ['0%', '0%'],
-  ['0turn', '0turn'],
+  ['0turn', '0deg'],
   ['0fr', '0fr'],
-  ['0ms', '0ms'],
+  ['0ms', '0s'],
   ['0s', '0s'],
   ['-0.0deg', '0deg'],
-  ['-0.0rad', '0rad'],
+  ['-0.0rad', '0deg'],
   ['-0.0%', '0%'],
-  ['-0.0turn', '0turn'],
+  ['-0.0turn', '0deg'],
   ['-0.0fr', '0fr'],
-  ['-0.0ms', '0ms'],
+  ['-0.0ms', '0s'],
   ['-0.0s', '0s'],
 ])('should not fold non-foldable units to `0`. Constant fold `%s` into `%s`', (input, expected) => {
   expect(constantFoldDeclaration(input)).toBe(expected)
diff --git a/packages/tailwindcss/src/constant-fold-declaration.ts b/packages/tailwindcss/src/constant-fold-declaration.ts
index fc2424ef7eba..9cc3feb76d27 100644
--- a/packages/tailwindcss/src/constant-fold-declaration.ts
+++ b/packages/tailwindcss/src/constant-fold-declaration.ts
@@ -9,33 +9,21 @@ export function constantFoldDeclaration(input: string): string {
   let valueAst = ValueParser.parse(input)
 
   ValueParser.walkDepth(valueAst, (valueNode, { replaceWith }) => {
-    // Convert `-0`, `+0`, `0.0`, … to `0`
-    // Convert `-0px`, `+0em`, `0.0rem`, … to `0`
+    // Canonicalize dimensions to their simplest form. This includes:
+    // - Convert `-0`, `+0`, `0.0`, … to `0`
+    // - Convert `-0px`, `+0em`, `0.0rem`, … to `0`
+    // - Convert units to an equivalent unit
     if (
       valueNode.kind === 'word' &&
-      valueNode.value !== '0' && // Already `0`, nothing to do
-      ((valueNode.value[0] === '-' && valueNode.value[1] === '0') || // `-0…`
-        (valueNode.value[0] === '+' && valueNode.value[1] === '0') || // `+0…`
-        valueNode.value[0] === '0') // `0…`
+      valueNode.value !== '0' // Already `0`, nothing to do
     ) {
-      let dimension = dimensions.get(valueNode.value)
-      if (dimension === null) return // This shouldn't happen
+      let canonical = canonicalizeDimension(valueNode.value)
+      if (canonical === null) return // Couldn't be canonicalized, nothing to do
+      if (canonical === valueNode.value) return // Already in canonical form, nothing to do
 
-      if (dimension[0] !== 0) return // Not a zero value, nothing to do
-
-      // Replace length units with just `0`
-      if (dimension[1] === null || isLength(valueNode.value)) {
-        folded = true
-        replaceWith(ValueParser.word('0'))
-        return
-      }
-
-      // Replace other units with `0<unit>`, e.g. `0%`, `0fr`, `0s`, …
-      else if (valueNode.value !== `0${dimension[1]}`) {
-        folded = true
-        replaceWith(ValueParser.word(`0${dimension[1]}`))
-        return
-      }
+      folded = true
+      replaceWith(ValueParser.word(canonical))
+      return
     }
 
     // Constant fold `calc()` expressions with two operands and one operator
@@ -124,3 +112,39 @@ export function constantFoldDeclaration(input: string): string {
 
   return folded ? ValueParser.toCss(valueAst) : input
 }
+
+function canonicalizeDimension(input: string, rem?: number): string | null {
+  let dimension = dimensions.get(input)
+  if (dimension === null) return null // This shouldn't happen
+
+  let [value, unit] = dimension
+  if (unit === null) return `${value}` // Already unitless, nothing to do
+
+  // Replace `0<length>` units with just `0`
+  if (value === 0 && isLength(input)) return '0'
+
+  // prettier-ignore
+  switch (unit.toLowerCase()) {
+    // <length> to px, https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#lengths
+    case 'in':  return `${value * 96}px`                  // 1in  = 96.000px
+    case 'cm':  return `${value * 96 / 2.54}px`           // 1cm  = 37.795px
+    case 'mm':  return `${value * 96 / 2.54 / 10}px`      // 1mm  =  3.779px
+    case 'q':   return `${value * 96 / 2.54 / 10 / 4}px`  //  1q  =  0.945px
+    case 'pc':  return `${value * 96 / 6}px`              // 1pc  = 16.000px
+    case 'pt':  return `${value * 96 / 72}px`             // 1pt  =  1.333px
+    case 'rem': return rem ? `${value * rem}px` : null    // 1rem = 16.000px (Assuming root font-size is 16px)
+
+    // <angle> to deg, https://developer.mozilla.org/en-US/docs/Web/CSS/angle
+    case 'grad': return `${value * 0.9}deg`               // 1grad =   0.900deg
+    case 'rad':  return `${value * 180 / Math.PI}deg`     //  1rad =  57.296deg
+    case 'turn': return `${value * 360}deg`               // 1turn = 360.000deg
+
+    // <time> to s, https://developer.mozilla.org/en-US/docs/Web/CSS/time
+    case 'ms':   return `${value / 1000}s`                // 1ms = 0.001s
+
+    // <frequency> to hz, https://developer.mozilla.org/en-US/docs/Web/CSS/frequency
+    case 'khz':  return `${value * 1000}hz`               // 1kHz = 1000Hz
+
+    default: return `${value}${unit}` // No canonicalization possible, return as-is
+  }
+}

From 5336ec0cd05e55b09170a449be8ccac4def95099 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 10 Oct 2025 14:51:59 +0200
Subject: [PATCH 2/7] add tests for passing in a `rem` value

+ Expose a `CanonicalizeOptions`
---
 .../src/canonicalize-candidates.test.ts       | 29 +++++++++++++++++--
 .../src/canonicalize-candidates.ts            | 10 +++++++
 packages/tailwindcss/src/design-system.ts     |  7 +++--
 packages/tailwindcss/src/intellisense.ts      |  2 +-
 4 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/packages/tailwindcss/src/canonicalize-candidates.test.ts b/packages/tailwindcss/src/canonicalize-candidates.test.ts
index b1ba62677610..75c0d45d182e 100644
--- a/packages/tailwindcss/src/canonicalize-candidates.test.ts
+++ b/packages/tailwindcss/src/canonicalize-candidates.test.ts
@@ -2,6 +2,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { describe, expect, test } from 'vitest'
 import { __unstable__loadDesignSystem } from '.'
+import type { CanonicalizeOptions } from './intellisense'
 import { DefaultMap } from './utils/default-map'
 
 const css = String.raw
@@ -63,7 +64,12 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
     return candidate
   }
 
-  async function expectCanonicalization(input: string, candidate: string, expected: string) {
+  async function expectCanonicalization(
+    input: string,
+    candidate: string,
+    expected: string,
+    options?: CanonicalizeOptions,
+  ) {
     candidate = prepare(candidate)
     expected = prepare(expected)
 
@@ -72,7 +78,7 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
     }
 
     let designSystem = await designSystems.get(__dirname).get(input)
-    let [actual] = designSystem.canonicalizeCandidates([candidate])
+    let [actual] = designSystem.canonicalizeCandidates([candidate], options)
 
     try {
       expect(actual).toBe(expected)
@@ -937,3 +943,22 @@ describe('theme to var', () => {
     ])
   })
 })
+
+describe('options', () => {
+  test('normalize `rem` units to `px`', async () => {
+    let designSystem = await __unstable__loadDesignSystem(
+      css`
+        @tailwind utilities;
+        @theme {
+          --spacing: 0.25rem;
+        }
+      `,
+      { base: __dirname },
+    )
+
+    expect(designSystem.canonicalizeCandidates(['m-[16px]'])).toEqual(['m-[16px]'])
+    expect(designSystem.canonicalizeCandidates(['m-[16px]'], { rem: 16 })).toEqual(['m-4'])
+    expect(designSystem.canonicalizeCandidates(['m-[16px]'], { rem: 64 })).toEqual(['m-1'])
+    expect(designSystem.canonicalizeCandidates(['m-[16px]'])).toEqual(['m-[16px]']) // Ensure options don't influence shared state
+  })
+})
diff --git a/packages/tailwindcss/src/canonicalize-candidates.ts b/packages/tailwindcss/src/canonicalize-candidates.ts
index 791da7844c32..5f75b96d074f 100644
--- a/packages/tailwindcss/src/canonicalize-candidates.ts
+++ b/packages/tailwindcss/src/canonicalize-candidates.ts
@@ -26,6 +26,16 @@ import { segment } from './utils/segment'
 import { toKeyPath } from './utils/to-key-path'
 import * as ValueParser from './value-parser'
 
+export interface CanonicalizeOptions {
+  /**
+   * The root font size in pixels. If provided, `rem` values will be normalized
+   * to `px` values.
+   *
+   * E.g.: `mt-[16px]` with `rem: 16` will become `mt-4` (assuming `--spacing: 0.25rem`).
+   */
+  rem?: number
+}
+
 export function canonicalizeCandidates(ds: DesignSystem, candidates: string[]): string[] {
   let result = new Set<string>()
   let cache = canonicalizeCandidateCache.get(ds)
diff --git a/packages/tailwindcss/src/design-system.ts b/packages/tailwindcss/src/design-system.ts
index 5f4450d50fbf..2dfa24128ae4 100644
--- a/packages/tailwindcss/src/design-system.ts
+++ b/packages/tailwindcss/src/design-system.ts
@@ -14,6 +14,7 @@ import {
   canonicalizeCandidates,
   getClassList,
   getVariants,
+  type CanonicalizeOptions,
   type ClassEntry,
   type VariantEntry,
 } from './intellisense'
@@ -54,7 +55,7 @@ export type DesignSystem = {
   resolveThemeValue(path: string, forceInline?: boolean): string | undefined
 
   trackUsedVariables(raw: string): void
-  canonicalizeCandidates(candidates: string[]): string[]
+  canonicalizeCandidates(candidates: string[], options?: CanonicalizeOptions): string[]
 
   // Used by IntelliSense
   candidatesToCss(classes: string[]): (string | null)[]
@@ -210,8 +211,8 @@ export function buildDesignSystem(theme: Theme): DesignSystem {
       trackUsedVariables.get(raw)
     },
 
-    canonicalizeCandidates(candidates: string[]) {
-      return canonicalizeCandidates(this, candidates)
+    canonicalizeCandidates(candidates: string[], options?: CanonicalizeOptions) {
+      return canonicalizeCandidates(this, candidates, options)
     },
   }
 
diff --git a/packages/tailwindcss/src/intellisense.ts b/packages/tailwindcss/src/intellisense.ts
index b04d8d212948..489fe5ffa9bf 100644
--- a/packages/tailwindcss/src/intellisense.ts
+++ b/packages/tailwindcss/src/intellisense.ts
@@ -3,7 +3,7 @@ import { applyVariant } from './compile'
 import type { DesignSystem } from './design-system'
 import { compare } from './utils/compare'
 import { DefaultMap } from './utils/default-map'
-export { canonicalizeCandidates } from './canonicalize-candidates'
+export { canonicalizeCandidates, type CanonicalizeOptions } from './canonicalize-candidates'
 
 interface ClassMetadata {
   modifiers: string[]

From 7f052b8e1f7c9b183b4eb8323022fe57a455fb93 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 10 Oct 2025 15:31:54 +0200
Subject: [PATCH 3/7] accept `rem` value when constant folding declarations

This allows us to migrate `rem` to `px` when provided
---
 packages/tailwindcss/src/constant-fold-declaration.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/tailwindcss/src/constant-fold-declaration.ts b/packages/tailwindcss/src/constant-fold-declaration.ts
index 9cc3feb76d27..2ae6b2557c60 100644
--- a/packages/tailwindcss/src/constant-fold-declaration.ts
+++ b/packages/tailwindcss/src/constant-fold-declaration.ts
@@ -4,7 +4,7 @@ import * as ValueParser from './value-parser'
 
 // Assumption: We already assume that we receive somewhat valid `calc()`
 // expressions. So we will see `calc(1 + 1)` and not `calc(1+1)`
-export function constantFoldDeclaration(input: string): string {
+export function constantFoldDeclaration(input: string, rem: number | null): string {
   let folded = false
   let valueAst = ValueParser.parse(input)
 
@@ -17,7 +17,7 @@ export function constantFoldDeclaration(input: string): string {
       valueNode.kind === 'word' &&
       valueNode.value !== '0' // Already `0`, nothing to do
     ) {
-      let canonical = canonicalizeDimension(valueNode.value)
+      let canonical = canonicalizeDimension(valueNode.value, rem)
       if (canonical === null) return // Couldn't be canonicalized, nothing to do
       if (canonical === valueNode.value) return // Already in canonical form, nothing to do
 
@@ -113,7 +113,7 @@ export function constantFoldDeclaration(input: string): string {
   return folded ? ValueParser.toCss(valueAst) : input
 }
 
-function canonicalizeDimension(input: string, rem?: number): string | null {
+function canonicalizeDimension(input: string, rem: number | null = null): string | null {
   let dimension = dimensions.get(input)
   if (dimension === null) return null // This shouldn't happen
 
@@ -132,7 +132,7 @@ function canonicalizeDimension(input: string, rem?: number): string | null {
     case 'q':   return `${value * 96 / 2.54 / 10 / 4}px`  //  1q  =  0.945px
     case 'pc':  return `${value * 96 / 6}px`              // 1pc  = 16.000px
     case 'pt':  return `${value * 96 / 72}px`             // 1pt  =  1.333px
-    case 'rem': return rem ? `${value * rem}px` : null    // 1rem = 16.000px (Assuming root font-size is 16px)
+    case 'rem': return rem !== null ? `${value * rem}px` : null    // 1rem = 16.000px (Assuming root font-size is 16px)
 
     // <angle> to deg, https://developer.mozilla.org/en-US/docs/Web/CSS/angle
     case 'grad': return `${value * 0.9}deg`               // 1grad =   0.900deg

From 57f071984e405b10fb1f5f07fc066a874e113972 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 10 Oct 2025 15:30:38 +0200
Subject: [PATCH 4/7] accept `SignatureOptions` instead of a `DesignSystem`

The `SignatureOptions` will contain the `DesignSystem` in addition to
other potential options.

Already added the `rem` option (naming up for debate) to canonicalize
`rem` to `px` values if provided.
---
 packages/tailwindcss/src/signatures.ts | 124 +++++++++++++------------
 1 file changed, 67 insertions(+), 57 deletions(-)

diff --git a/packages/tailwindcss/src/signatures.ts b/packages/tailwindcss/src/signatures.ts
index 54738072b87e..493309b6cc82 100644
--- a/packages/tailwindcss/src/signatures.ts
+++ b/packages/tailwindcss/src/signatures.ts
@@ -11,6 +11,21 @@ import * as ValueParser from './value-parser'
 
 const FLOATING_POINT_PERCENTAGE = /\d*\.\d+(?:[eE][+-]?\d+)?%/g
 
+export interface SignatureOptions {
+  /**
+   * The root font size in pixels. If provided, `rem` values will be normalized
+   * to `px` values.
+   *
+   * E.g.: `mt-[16px]` with `rem: 16` will become `mt-4` (assuming `--spacing: 0.25rem`).
+   */
+  rem: number | null
+
+  /**
+   * The design system to use for computing the signature of candidates.
+   */
+  designSystem: DesignSystem
+}
+
 // Given a utility, compute a signature that represents the utility. The
 // signature will be a normalised form of the generated CSS for the utility, or
 // a unique symbol if the utility is not valid. The class in the selector will
@@ -27,10 +42,9 @@ const FLOATING_POINT_PERCENTAGE = /\d*\.\d+(?:[eE][+-]?\d+)?%/g
 // | `flex`           | `.x { display: flex; }` |
 //
 // These produce the same signature, therefore they represent the same utility.
-export const computeUtilitySignature = new DefaultMap<
-  DesignSystem,
-  DefaultMap<string, string | Symbol>
->((designSystem) => {
+export const computeUtilitySignature = new DefaultMap((options: SignatureOptions) => {
+  let { rem, designSystem } = options
+
   return new DefaultMap<string, string | Symbol>((utility) => {
     try {
       // Ensure the prefix is added to the utility if it is not already present.
@@ -208,7 +222,7 @@ export const computeUtilitySignature = new DefaultMap<
           //       → `calc(0.25rem * 4)`       ← this is the case we will see
           //                                     after inlining the variable
           //       → `1rem`
-          node.value = constantFoldDeclaration(node.value)
+          node.value = constantFoldDeclaration(node.value, rem)
 
           // We will normalize the `node.value`, this is the same kind of logic
           // we use when printing arbitrary values. It will remove unnecessary
@@ -237,45 +251,44 @@ export const computeUtilitySignature = new DefaultMap<
 // For all functional utilities, we can compute static-like utilities by
 // essentially pre-computing the values and modifiers. This is a bit slow, but
 // also only has to happen once per design system.
-export const preComputedUtilities = new DefaultMap<DesignSystem, DefaultMap<string, string[]>>(
-  (ds) => {
-    let signatures = computeUtilitySignature.get(ds)
-    let lookup = new DefaultMap<string, string[]>(() => [])
-
-    for (let [className, meta] of ds.getClassList()) {
-      let signature = signatures.get(className)
-      if (typeof signature !== 'string') continue
-
-      // Skip the utility if `-{utility}-0` has the same signature as
-      // `{utility}-0` (its positive version). This will prefer positive values
-      // over negative values.
-      if (className[0] === '-' && className.endsWith('-0')) {
-        let positiveSignature = signatures.get(className.slice(1))
-        if (typeof positiveSignature === 'string' && signature === positiveSignature) {
-          continue
-        }
+export const preComputedUtilities = new DefaultMap((options: SignatureOptions) => {
+  let { designSystem } = options
+  let signatures = computeUtilitySignature.get(options)
+  let lookup = new DefaultMap<string, string[]>(() => [])
+
+  for (let [className, meta] of designSystem.getClassList()) {
+    let signature = signatures.get(className)
+    if (typeof signature !== 'string') continue
+
+    // Skip the utility if `-{utility}-0` has the same signature as
+    // `{utility}-0` (its positive version). This will prefer positive values
+    // over negative values.
+    if (className[0] === '-' && className.endsWith('-0')) {
+      let positiveSignature = signatures.get(className.slice(1))
+      if (typeof positiveSignature === 'string' && signature === positiveSignature) {
+        continue
       }
+    }
 
-      lookup.get(signature).push(className)
-
-      for (let modifier of meta.modifiers) {
-        // Modifiers representing numbers can be computed and don't need to be
-        // pre-computed. Doing the math and at the time of writing this, this
-        // would save you 250k additionally pre-computed utilities...
-        if (isValidSpacingMultiplier(modifier)) {
-          continue
-        }
+    lookup.get(signature).push(className)
 
-        let classNameWithModifier = `${className}/${modifier}`
-        let signature = signatures.get(classNameWithModifier)
-        if (typeof signature !== 'string') continue
-        lookup.get(signature).push(classNameWithModifier)
+    for (let modifier of meta.modifiers) {
+      // Modifiers representing numbers can be computed and don't need to be
+      // pre-computed. Doing the math and at the time of writing this, this
+      // would save you 250k additionally pre-computed utilities...
+      if (isValidSpacingMultiplier(modifier)) {
+        continue
       }
+
+      let classNameWithModifier = `${className}/${modifier}`
+      let signature = signatures.get(classNameWithModifier)
+      if (typeof signature !== 'string') continue
+      lookup.get(signature).push(classNameWithModifier)
     }
+  }
 
-    return lookup
-  },
-)
+  return lookup
+})
 
 // Given a variant, compute a signature that represents the variant. The
 // signature will be a normalised form of the generated CSS for the variant, or
@@ -290,10 +303,8 @@ export const preComputedUtilities = new DefaultMap<DesignSystem, DefaultMap<stri
 // | `focus:flex`     | `.x:focus { display: flex; }` |
 //
 // These produce the same signature, therefore they represent the same variant.
-export const computeVariantSignature = new DefaultMap<
-  DesignSystem,
-  DefaultMap<string, string | Symbol>
->((designSystem) => {
+export const computeVariantSignature = new DefaultMap((options: SignatureOptions) => {
+  let { designSystem } = options
   return new DefaultMap<string, string | Symbol>((variant) => {
     try {
       // Ensure the prefix is added to the utility if it is not already present.
@@ -383,23 +394,22 @@ export const computeVariantSignature = new DefaultMap<
   })
 })
 
-export const preComputedVariants = new DefaultMap<DesignSystem, DefaultMap<string, string[]>>(
-  (designSystem) => {
-    let signatures = computeVariantSignature.get(designSystem)
-    let lookup = new DefaultMap<string, string[]>(() => [])
-
-    // Actual static variants
-    for (let [root, variant] of designSystem.variants.entries()) {
-      if (variant.kind === 'static') {
-        let signature = signatures.get(root)
-        if (typeof signature !== 'string') continue
-        lookup.get(signature).push(root)
-      }
+export const preComputedVariants = new DefaultMap((options: SignatureOptions) => {
+  let { designSystem } = options
+  let signatures = computeVariantSignature.get(options)
+  let lookup = new DefaultMap<string, string[]>(() => [])
+
+  // Actual static variants
+  for (let [root, variant] of designSystem.variants.entries()) {
+    if (variant.kind === 'static') {
+      let signature = signatures.get(root)
+      if (typeof signature !== 'string') continue
+      lookup.get(signature).push(root)
     }
+  }
 
-    return lookup
-  },
-)
+  return lookup
+})
 
 function temporarilyDisableThemeInline<T>(designSystem: DesignSystem, cb: () => T): T {
   // Turn off `@theme inline` feature such that `@theme` and `@theme inline` are

From b059d94a25d6ab1422507e6a592bb794d56be910 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 10 Oct 2025 15:33:10 +0200
Subject: [PATCH 5/7] canonicalize using `SignatureOptions`

Instead of a top-level `DesignSystem`, we can use the
`SignatureOptions`. We can create `CanonicalizeOptions` or similar in
the future that contains `SignatureOptions` _if_ we need values while
canonicalizing values but aren't needed when creating a signature. Just
didn't want to add this as long as we don't need it.

This also changes the APIs for utility and variant canonicalization
steps. The APIs look like this:

```ts
type VariantCanonicalizationFunction = (variant: Variant, options: SignatureOptions) => Variant | Variant[]
type UtilityCanonicalizationFunction = (candidate: Candidate, options: SignatureOptions) => Candidate
```
---
 .../src/canonicalize-candidates.ts            | 114 ++++++++++++------
 1 file changed, 76 insertions(+), 38 deletions(-)

diff --git a/packages/tailwindcss/src/canonicalize-candidates.ts b/packages/tailwindcss/src/canonicalize-candidates.ts
index 5f75b96d074f..8df31af09091 100644
--- a/packages/tailwindcss/src/canonicalize-candidates.ts
+++ b/packages/tailwindcss/src/canonicalize-candidates.ts
@@ -16,6 +16,7 @@ import {
   computeVariantSignature,
   preComputedUtilities,
   preComputedVariants,
+  type SignatureOptions,
 } from './signatures'
 import type { Writable } from './types'
 import { DefaultMap } from './utils/default-map'
@@ -36,19 +37,37 @@ export interface CanonicalizeOptions {
   rem?: number
 }
 
-export function canonicalizeCandidates(ds: DesignSystem, candidates: string[]): string[] {
+const optionsCache = new DefaultMap((designSystem: DesignSystem) => {
+  return new DefaultMap((rem: number | null = null) => {
+    return { designSystem, rem } satisfies SignatureOptions
+  })
+})
+
+export function createSignatureOptions(
+  designSystem: DesignSystem,
+  options?: CanonicalizeOptions,
+): SignatureOptions {
+  return optionsCache.get(designSystem).get(options?.rem ?? null)
+}
+
+export function canonicalizeCandidates(
+  designSystem: DesignSystem,
+  candidates: string[],
+  options?: CanonicalizeOptions,
+): string[] {
   let result = new Set<string>()
-  let cache = canonicalizeCandidateCache.get(ds)
+  let cache = canonicalizeCandidateCache.get(createSignatureOptions(designSystem, options))
   for (let candidate of candidates) {
     result.add(cache.get(candidate))
   }
   return Array.from(result)
 }
 
-const canonicalizeCandidateCache = new DefaultMap((ds: DesignSystem) => {
+const canonicalizeCandidateCache = new DefaultMap((options: SignatureOptions) => {
+  let ds = options.designSystem
   let prefix = ds.theme.prefix ? `${ds.theme.prefix}:` : ''
-  let variantCache = canonicalizeVariantCache.get(ds)
-  let utilityCache = canonicalizeUtilityCache.get(ds)
+  let variantCache = canonicalizeVariantCache.get(options)
+  let utilityCache = canonicalizeUtilityCache.get(options)
 
   return new DefaultMap<string, string>((rawCandidate: string, self) => {
     for (let candidate of ds.parseCandidate(rawCandidate)) {
@@ -105,21 +124,26 @@ const canonicalizeCandidateCache = new DefaultMap((ds: DesignSystem) => {
   })
 })
 
-const VARIANT_CANONICALIZATIONS = [
+type VariantCanonicalizationFunction = (
+  variant: Variant,
+  options: SignatureOptions,
+) => Variant | Variant[]
+
+const VARIANT_CANONICALIZATIONS: VariantCanonicalizationFunction[] = [
   themeToVarVariant,
   arbitraryValueToBareValueVariant,
   modernizeArbitraryValuesVariant,
   arbitraryVariants,
 ]
 
-const canonicalizeVariantCache = new DefaultMap((ds: DesignSystem) => {
+const canonicalizeVariantCache = new DefaultMap((options: SignatureOptions) => {
   return new DefaultMap((variant: Variant): Variant[] => {
     let replacement = [variant]
     for (let fn of VARIANT_CANONICALIZATIONS) {
       for (let current of replacement.splice(0)) {
         // A single variant can result in multiple variants, e.g.:
         // `[&>[data-selected]]:flex` → `*:data-selected:flex`
-        let result = fn(ds, cloneVariant(current))
+        let result = fn(cloneVariant(current), options)
         if (Array.isArray(result)) {
           replacement.push(...result)
           continue
@@ -132,7 +156,12 @@ const canonicalizeVariantCache = new DefaultMap((ds: DesignSystem) => {
   })
 })
 
-const UTILITY_CANONICALIZATIONS = [
+type UtilityCanonicalizationFunction = (
+  candidate: Candidate,
+  options: SignatureOptions,
+) => Candidate
+
+const UTILITY_CANONICALIZATIONS: UtilityCanonicalizationFunction[] = [
   bgGradientToLinear,
   themeToVarUtility,
   arbitraryUtilities,
@@ -143,16 +172,17 @@ const UTILITY_CANONICALIZATIONS = [
   optimizeModifier,
 ]
 
-const canonicalizeUtilityCache = new DefaultMap((ds: DesignSystem) => {
+const canonicalizeUtilityCache = new DefaultMap((options: SignatureOptions) => {
+  let designSystem = options.designSystem
   return new DefaultMap((rawCandidate: string): string => {
-    for (let readonlyCandidate of ds.parseCandidate(rawCandidate)) {
+    for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
       let replacement = cloneCandidate(readonlyCandidate) as Writable<typeof readonlyCandidate>
 
       for (let fn of UTILITY_CANONICALIZATIONS) {
-        replacement = fn(ds, replacement)
+        replacement = fn(replacement, options)
       }
 
-      let canonicalizedCandidate = ds.printCandidate(replacement)
+      let canonicalizedCandidate = designSystem.printCandidate(replacement)
       if (rawCandidate !== canonicalizedCandidate) {
         return canonicalizedCandidate
       }
@@ -165,7 +195,7 @@ const canonicalizeUtilityCache = new DefaultMap((ds: DesignSystem) => {
 // ----
 
 const DIRECTIONS = ['t', 'tr', 'r', 'br', 'b', 'bl', 'l', 'tl']
-function bgGradientToLinear(_: DesignSystem, candidate: Candidate) {
+function bgGradientToLinear(candidate: Candidate) {
   if (candidate.kind === 'static' && candidate.root.startsWith('bg-gradient-to-')) {
     let direction = candidate.root.slice(15)
 
@@ -188,8 +218,8 @@ const enum Convert {
   MigrateThemeOnly = 1 << 1,
 }
 
-function themeToVarUtility(designSystem: DesignSystem, candidate: Candidate): Candidate {
-  let convert = converterCache.get(designSystem)
+function themeToVarUtility(candidate: Candidate, options: SignatureOptions): Candidate {
+  let convert = converterCache.get(options.designSystem)
 
   if (candidate.kind === 'arbitrary') {
     let [newValue, modifier] = convert(
@@ -220,8 +250,8 @@ function themeToVarUtility(designSystem: DesignSystem, candidate: Candidate): Ca
   return candidate
 }
 
-function themeToVarVariant(designSystem: DesignSystem, variant: Variant): Variant | Variant[] {
-  let convert = converterCache.get(designSystem)
+function themeToVarVariant(variant: Variant, options: SignatureOptions): Variant | Variant[] {
+  let convert = converterCache.get(options.designSystem)
 
   let iterator = walkVariants(variant)
   for (let [variant] of iterator) {
@@ -555,7 +585,7 @@ const spacing = new DefaultMap<DesignSystem, DefaultMap<string, number | null> |
   })
 })
 
-function arbitraryUtilities(designSystem: DesignSystem, candidate: Candidate): Candidate {
+function arbitraryUtilities(candidate: Candidate, options: SignatureOptions): Candidate {
   // We are only interested in arbitrary properties and arbitrary values
   if (
     // Arbitrary property
@@ -566,8 +596,9 @@ function arbitraryUtilities(designSystem: DesignSystem, candidate: Candidate): C
     return candidate
   }
 
-  let utilities = preComputedUtilities.get(designSystem)
-  let signatures = computeUtilitySignature.get(designSystem)
+  let designSystem = options.designSystem
+  let utilities = preComputedUtilities.get(options)
+  let signatures = computeUtilitySignature.get(options)
 
   let targetCandidateString = designSystem.printCandidate(candidate)
 
@@ -771,14 +802,15 @@ function allVariablesAreUsed(
 
 // ----
 
-function bareValueUtilities(designSystem: DesignSystem, candidate: Candidate): Candidate {
+function bareValueUtilities(candidate: Candidate, options: SignatureOptions): Candidate {
   // We are only interested in bare value utilities
   if (candidate.kind !== 'functional' || candidate.value?.kind !== 'named') {
     return candidate
   }
 
-  let utilities = preComputedUtilities.get(designSystem)
-  let signatures = computeUtilitySignature.get(designSystem)
+  let designSystem = options.designSystem
+  let utilities = preComputedUtilities.get(options)
+  let signatures = computeUtilitySignature.get(options)
 
   let targetCandidateString = designSystem.printCandidate(candidate)
 
@@ -847,8 +879,9 @@ function bareValueUtilities(designSystem: DesignSystem, candidate: Candidate): C
 
 const DEPRECATION_MAP = new Map([['order-none', 'order-0']])
 
-function deprecatedUtilities(designSystem: DesignSystem, candidate: Candidate): Candidate {
-  let signatures = computeUtilitySignature.get(designSystem)
+function deprecatedUtilities(candidate: Candidate, options: SignatureOptions): Candidate {
+  let designSystem = options.designSystem
+  let signatures = computeUtilitySignature.get(options)
 
   let targetCandidateString = printUnprefixedCandidate(designSystem, candidate)
 
@@ -870,9 +903,10 @@ function deprecatedUtilities(designSystem: DesignSystem, candidate: Candidate):
 
 // ----
 
-function arbitraryVariants(designSystem: DesignSystem, variant: Variant): Variant | Variant[] {
-  let signatures = computeVariantSignature.get(designSystem)
-  let variants = preComputedVariants.get(designSystem)
+function arbitraryVariants(variant: Variant, options: SignatureOptions): Variant | Variant[] {
+  let designSystem = options.designSystem
+  let signatures = computeVariantSignature.get(options)
+  let variants = preComputedVariants.get(options)
 
   let iterator = walkVariants(variant)
   for (let [variant] of iterator) {
@@ -897,8 +931,9 @@ function arbitraryVariants(designSystem: DesignSystem, variant: Variant): Varian
 
 // ----
 
-function dropUnnecessaryDataTypes(designSystem: DesignSystem, candidate: Candidate): Candidate {
-  let signatures = computeUtilitySignature.get(designSystem)
+function dropUnnecessaryDataTypes(candidate: Candidate, options: SignatureOptions): Candidate {
+  let designSystem = options.designSystem
+  let signatures = computeUtilitySignature.get(options)
 
   if (
     candidate.kind === 'functional' &&
@@ -921,15 +956,16 @@ function dropUnnecessaryDataTypes(designSystem: DesignSystem, candidate: Candida
 // ----
 
 function arbitraryValueToBareValueUtility(
-  designSystem: DesignSystem,
   candidate: Candidate,
+  options: SignatureOptions,
 ): Candidate {
   // We are only interested in functional utilities with arbitrary values
   if (candidate.kind !== 'functional' || candidate.value?.kind !== 'arbitrary') {
     return candidate
   }
 
-  let signatures = computeUtilitySignature.get(designSystem)
+  let designSystem = options.designSystem
+  let signatures = computeUtilitySignature.get(options)
 
   let expectedSignature = signatures.get(designSystem.printCandidate(candidate))
   if (expectedSignature === null) return candidate
@@ -945,7 +981,7 @@ function arbitraryValueToBareValueUtility(
   return candidate
 }
 
-function arbitraryValueToBareValueVariant(_: DesignSystem, variant: Variant): Variant | Variant[] {
+function arbitraryValueToBareValueVariant(variant: Variant): Variant | Variant[] {
   let iterator = walkVariants(variant)
   for (let [variant] of iterator) {
     // Convert `data-[selected]` to `data-selected`
@@ -1093,11 +1129,12 @@ function isAttributeSelector(node: SelectorParser.SelectorAstNode): boolean {
 }
 
 function modernizeArbitraryValuesVariant(
-  designSystem: DesignSystem,
   variant: Variant,
+  options: SignatureOptions,
 ): Variant | Variant[] {
   let result = [variant]
-  let signatures = computeVariantSignature.get(designSystem)
+  let designSystem = options.designSystem
+  let signatures = computeVariantSignature.get(options)
 
   let iterator = walkVariants(variant)
   for (let [variant, parent] of iterator) {
@@ -1452,7 +1489,7 @@ function modernizeArbitraryValuesVariant(
 // - `/[100%]`  → `/100`    → <empty>
 // - `/100`     → <empty>
 //
-function optimizeModifier(designSystem: DesignSystem, candidate: Candidate): Candidate {
+function optimizeModifier(candidate: Candidate, options: SignatureOptions): Candidate {
   // We are only interested in functional or arbitrary utilities with a modifier
   if (
     (candidate.kind !== 'functional' && candidate.kind !== 'arbitrary') ||
@@ -1461,7 +1498,8 @@ function optimizeModifier(designSystem: DesignSystem, candidate: Candidate): Can
     return candidate
   }
 
-  let signatures = computeUtilitySignature.get(designSystem)
+  let designSystem = options.designSystem
+  let signatures = computeUtilitySignature.get(options)
 
   let targetSignature = signatures.get(designSystem.printCandidate(candidate))
   let modifier = candidate.modifier

From af9843bd848633ae32994294d47ffd06c2206ab3 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 10 Oct 2025 15:36:10 +0200
Subject: [PATCH 6/7] use signature options in upgrade tool

---
 .../codemods/template/migrate-arbitrary-variants.ts  |  6 ++++--
 .../src/codemods/template/migrate.ts                 | 12 ++++++------
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/migrate-arbitrary-variants.ts b/packages/@tailwindcss-upgrade/src/codemods/template/migrate-arbitrary-variants.ts
index 9d8b176bd858..c1b9669ac466 100644
--- a/packages/@tailwindcss-upgrade/src/codemods/template/migrate-arbitrary-variants.ts
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/migrate-arbitrary-variants.ts
@@ -1,4 +1,5 @@
 import { cloneCandidate } from '../../../../tailwindcss/src/candidate'
+import { createSignatureOptions } from '../../../../tailwindcss/src/canonicalize-candidates'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import {
@@ -14,8 +15,9 @@ export function migrateArbitraryVariants(
   _userConfig: Config | null,
   rawCandidate: string,
 ): string {
-  let signatures = computeVariantSignature.get(designSystem)
-  let variants = preComputedVariants.get(designSystem)
+  let signatureOptions = createSignatureOptions(designSystem)
+  let signatures = computeVariantSignature.get(signatureOptions)
+  let variants = preComputedVariants.get(signatureOptions)
 
   for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
     // We are only interested in the variants
diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts b/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts
index d402847fc0e9..6060d8020cd1 100644
--- a/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts
@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises'
 import path, { extname } from 'node:path'
+import { createSignatureOptions } from '../../../../tailwindcss/src/canonicalize-candidates'
 import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
 import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
 import { computeUtilitySignature } from '../../../../tailwindcss/src/signatures'
@@ -39,11 +40,10 @@ export const DEFAULT_MIGRATIONS: Migration[] = [
   migrateModernizeArbitraryValues,
 ]
 
-let migrateCached = new DefaultMap<
-  DesignSystem,
-  DefaultMap<Config | null, DefaultMap<string, Promise<string>>>
->((designSystem) => {
-  return new DefaultMap((userConfig) => {
+let migrateCached = new DefaultMap((designSystem: DesignSystem) => {
+  let options = createSignatureOptions(designSystem)
+
+  return new DefaultMap((userConfig: Config | null) => {
     return new DefaultMap(async (rawCandidate) => {
       let original = rawCandidate
 
@@ -57,7 +57,7 @@ let migrateCached = new DefaultMap<
       // Verify that the candidate actually makes sense at all. E.g.: `duration`
       // is not a valid candidate, but it will parse because `duration-<number>`
       // exists.
-      let signature = computeUtilitySignature.get(designSystem).get(rawCandidate)
+      let signature = computeUtilitySignature.get(options).get(rawCandidate)
       if (typeof signature !== 'string') return original
 
       return rawCandidate

From edd6b21e289718846ac8273ae1240cc7e8973ac2 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 10 Oct 2025 15:36:32 +0200
Subject: [PATCH 7/7] make TypeScript happy

Oops.
---
 .../template/migrate-modernize-arbitrary-values.test.ts         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/migrate-modernize-arbitrary-values.test.ts b/packages/@tailwindcss-upgrade/src/codemods/template/migrate-modernize-arbitrary-values.test.ts
index 9f26f0188606..b1887ae0bd7e 100644
--- a/packages/@tailwindcss-upgrade/src/codemods/template/migrate-modernize-arbitrary-values.test.ts
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/migrate-modernize-arbitrary-values.test.ts
@@ -17,7 +17,7 @@ function migrate(designSystem: DesignSystem, userConfig: UserConfig | null, rawC
     migratePrefix,
     migrateModernizeArbitraryValues,
     migrateArbitraryVariants,
-    (designSystem: DesignSystem, _, rawCandidate: string) => {
+    (designSystem: DesignSystem, _: UserConfig | null, rawCandidate: string) => {
       return designSystem.canonicalizeCandidates([rawCandidate]).pop() ?? rawCandidate
     },
   ]) {