Ensure @variant can be used in JS based APIs

[RobinMalfait]

This PR doesn't fix any issues, but it does add an integration test (as a regression test) to make sure that @variant with default variants and custom variants can be used inside of JS based plugin APIs.

In Tailwind CSS v4.3.1 we introduced a PR that handles @variant in the addBase Plugin API (#19480). This was a bit of an older PR, but the tests made sense, so it was merged.

However, by introducing that PR, we introduced a bug that the @variant was handled too early. If you added custom variants later and used it in the addBase, then you would get an error since the variant isn't available (yet).

That issue was fixed by #20247

Now the question remains, why did we even have the original PR when it already worked?

The use case we had was using @variant as part of the @tailwindcss/typography plugin configuration for one of our templates. I was indeed able to reproduce the issue where @variant lg was seen in the output CSS file.

Turns out that this template was using @tailwindcss/typography + @variant in the configuration, but it was also using Tailwind CSS v4.1.15.

Upgrading to the latest version automagically fixed the issue we had. This is also the behavior you can see in the integration test.

The correct behavior was introduced in an even older PR #19263

All that said, everything should work in the next release related to @variant usages inside JS based APIs.

Tiny improvement

While debugging what's going on, I noticed that we looped over the AST to get some nodes out and we did that twice. This PR also improves that by re-using the same list of nodes instead of computing it twice. This won't have a huge impact, but it happened while compiling every single utility which is not ideal.

Test plan

1. All tests should pass
2. I can't see @variant in the output CSS file

Input:

Before:

After:

[greptile-apps]

Confidence Score: 5/5

Safe to merge — the only production code change is a single-variable extraction that eliminates a redundant .map() call, and the new integration test locks in the correct behavior end-to-end.

Both changes are low-risk. The design-system.ts diff is a pure refactor: substituteFunctions and substituteAtVariant mutate AST node objects in place and do not push or splice the array they receive, so sharing the same nodes reference between the two calls is equivalent to the original two-array approach. The integration test is additive and its inline snapshot was generated from a verified passing run, covering both the sm responsive variant and the custom @custom-variant composed together.

No files require special attention.

_{Reviews (1): Last reviewed commit: "reuse nodes" | Re-trigger Greptile}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 32b8110b-982c-406f-9f89-a1f8d6154bbf

📥 Commits

Reviewing files that changed from the base of the PR and between 707c23b and 6bb9d2d.

📒 Files selected for processing (2)

• integrations/cli/plugins.test.ts
• packages/tailwindcss/src/design-system.ts

---

Walkthrough

buildDesignSystem's internal compileAstNodes function is refactored to compute the array of AST node objects once and reuse it for both the substituteFunctions and substituteAtVariant calls, rather than performing two separate inline remaps of the same ast array. A new CLI integration test is added for @tailwindcss/typography that configures a @custom-variant, uses @variant sm:custom inside a plugin-supplied rule, builds via the CLI, and asserts that the @variant directive does not appear literally in the output and that the hr selector is correctly expanded to a :where(...) block scoped with @media (width >= 640px) and &.custom.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Ensure @variant can be used in JS based APIs' accurately summarizes the main change—adding a regression test for @variant usage in JavaScript-based plugin APIs.
Description check	✅ Passed	The description is directly related to the changeset, providing comprehensive context about the @variant handling in JS-based APIs, prior fixes, and the regression test being added.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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