canonicalizeCandidates fails when using @utility / @apply with breakpoint variants

[smnbbrv]

What version of Tailwind CSS are you using?

v4.3.0

What build tool (or framework if it abstracts the build tool) are you using?

N/A

What version of Node.js are you using?

v24

What browser are you using?

N/A

What operating system are you using?

N/A

Reproduction URL

Repository, see at-apply-with-breakpoint.mjs

Run with npm install && npm run at-apply-with-breakpoint

Describe your issue

Discovered by using eslint-plugin-better-tailwindcss.

Using breakpoints in utility classes (via apply) breaks the canonical classes discovery. Example:

@import "tailwindcss";

@utility foo {
  @apply text-[13px] font-medium md:text-[15px];
}

The md:text-[15px] part is the breaking one. If it gets removed, everything works just fine.

design.canonicalizeCandidates(['text-[13px]', 'font-medium', 'md:text-[15px]'], { collapse: true, logicalToPhysical: true, rem: 16 })
//   without md:text-[15px] in @apply body: ['foo']  (correct)
//   with md:text-[15px] in @apply body:    ['text-[13px]', 'font-medium', 'md:text-[15px]']  (unchanged)

Or a more complex (real life) example:

// @utility copy-small         { @apply text-[13px] md:text-[15px]; }
// @utility copy-small-medium  { @apply text-[13px] font-medium md:text-[15px]; }
design.canonicalizeCandidates(['copy-small', 'font-medium'], opts)
//   expected: ['copy-small-medium']
//   actual:   ['copy-small', 'font-medium']

[RobinMalfait]

Hey! Moved this to an ideas discussion because this currently isn't a bug but more like a missing feature.

Right now the canonicalization process is relatively complex (and slow to setup), and to make things simpler we only canonicalize classes in groups based on their used variants. So in your case, we will only canonicalize 2 groups: ['text-[13px]', 'font-medium'] and ['md:text-[15px]'] but we won't combine them.

There are some other internal pending things we need to do before we can explore this bigger search space.

For now, I'll keep this as a future suggestion instead of a bug since the classes going in are still valid and should still work as expected.

[smnbbrv]

So in your case, we will only canonicalize 2 groups: ['text-[13px]', 'font-medium'] and ['md:text-[15px]'] but we won't combine them.

That explains a lot. What's interesting, the eslint plugin for VSCode somehow manages to find the proper class replacements. The investigation pointed to this problem, and it is clear why the CLI does not find it, but still does not explain how the IDE plugin manages that. Mystery.

Thanks for keeping it on the radar!