Make `--theme(…)` return CSS variables by philipp-spiess · Pull Request #17036 · tailwindlabs/tailwindcss

philipp-spiess · 2025-03-07T12:26:37Z

This PR changes the --theme(…) function now return CSS var(…) definitions unless used in places where var(…) is not valid CSS (e.g. in @media (width >= theme(--breakpoint-md))):

/* input */
@theme {
  --color-red: red;
}
.red {
  color: --theme(--color-red);
}

/* output */
:root, :host {
  --color-red: red;
}
.red {
  color: var(--color-red);
}

Furthermore, this adds an --theme(… inline) option to the --theme(…) function to force the resolution to be inline, e.g.:

/* input */
@theme {
  --color-red: red;
}
.red {
  color: --theme(--color-red inline);
}

/* output */
.red {
  color: red;
}

This PR also changes preflight and the default theme to use this new --theme(…) function to ensure variables are prefixed correctly.

Test plan

Added unit tests and a test that pulls in the whole preflight under a prefix theme.

packages/@tailwindcss-postcss/src/__snapshots__/index.test.ts.snap

philipp-spiess · 2025-03-07T12:34:33Z

packages/tailwindcss/src/css-functions.ts

 }

-function theme(designSystem: DesignSystem, path: string, ...fallback: string[]) {
+function theme(designSystem: DesignSystem, source: AstNode, path: string, ...fallback: string[]) {


We're passing through the source now where we found the value that contains the function invocation.

philipp-spiess · 2025-03-07T12:35:11Z

packages/tailwindcss/src/design-system.ts


  getVariantOrder(): Map<Variant, number>
-  resolveThemeValue(path: string): string | undefined
+  resolveThemeValue(path: string, forceInline?: boolean): string | undefined


I have to make this optional because of IntelliSense unfortunately. Also decided to make a boolean here since don't leak the ThemeOption enum beyond internal APIs right now.

packages/tailwindcss/theme.css

philipp-spiess · 2025-03-10T13:50:10Z

packages/@tailwindcss-postcss/src/__snapshots__/index.test.ts.snap

-    --default-font-feature-settings: var(--font-sans--font-feature-settings);
-    --default-font-variation-settings: var(--font-sans--font-variation-settings);
    --default-mono-font-family: var(--font-mono);
-    --default-mono-font-feature-settings: var(--font-mono--font-feature-settings);
-    --default-mono-font-variation-settings: var(--font-mono--font-variation-settings);


Now that the --default-font-feature-settings theme variable is defined as:

@theme { --default-font-feature-settings: --theme(--font-sans--font-feature-settings, initial); }

The value is resolved to initial (and thus omitted) because we know that --font-sans--font-feature-settings is not defined in the theme. Note that this implies that values referenced via --theme(…) can not be defined at runtime only and NEED to be in the @theme block. I think this is a reasonable thing to do since we also error when it's not in the @theme block (unless a fallback is specified like it is here).

…ack)` call

thecrypticace · 2025-03-17T17:50:58Z

packages/tailwindcss/src/css-functions.ts

+  // Inject the fallback…
+  //
+  // - …as the value if the value returned is `initial`
+  // - …expect any `initial` fallbacks on `var(…)`, `theme(…)`, or `--theme(…)`


Is this supposed to say except?

This entire comment is kinda hard to parse for me

I reworked this part, thanks

thecrypticace · 2025-03-17T17:52:38Z

packages/tailwindcss/src/css-functions.ts

+      node.nodes.push({
+        kind: 'word',
+        value: `, ${fallback}`,
+      })


This seems fine but don't we technically treat the , as a separate node when parsing? Should we do that here too?

yeah we do, the fallback could also consist of other, nested, functions etc. It's technically more correct to parse the fallback as well but it felt super wasteful to parse it just so it's stringified in the next line. If we ever change stuff so that the stringification won't work anymore if the word node contains stuff it shouldn't, we also have unit tests that would let us know this breaks so I decided to just put it in as a word node.

thecrypticace · 2025-03-17T17:59:08Z

packages/tailwindcss/src/css-functions.test.ts

+    `)
+  })
+
+  test('--theme(…) does not inject the fallback if the fallback is `initial`', async () => {


This test name feels wrong. The different thing about this test is that the theme key exists and therefore the fallback isn't used.

good catch!

thecrypticace

left some comments about test names, comments, and a thing about the AST

@theme

Closes tailwindlabs#16945 This PR changes the `--theme(…)` function now return CSS `var(…)` definitions unless used in places where `var(…)` is not valid CSS (e.g. in `@media (width >= theme(--breakpoint-md))`): ```css /* input */ @theme { --color-red: red; } .red { color: --theme(--color-red); } /* output */ :root, :host { --color-red: red; } .red { color: var(--color-red); } ``` Furthermore, this adds an `--theme(… inline)` option to the `--theme(…)` function to force the resolution to be inline, e.g.: ```css /* input */ @theme { --color-red: red; } .red { color: --theme(--color-red inline); } /* output */ .red { color: red; } ``` This PR also changes preflight and the default theme to use this new `--theme(…)` function to ensure variables are prefixed correctly. ## Test plan - Added unit tests and a test that pulls in the whole preflight under a prefix theme.

philipp-spiess requested a review from a team as a code owner March 7, 2025 12:26

philipp-spiess commented Mar 7, 2025

View reviewed changes

philipp-spiess commented Mar 10, 2025

View reviewed changes

philipp-spiess force-pushed the chore/--theme-as-var branch from f03d2cc to d51babe Compare March 10, 2025 13:57

philipp-spiess added 8 commits March 17, 2025 15:43

Add ability to force theme function resolution as inline

1ce8bd9

Force-inline when --theme(…) is used inside at rules

972b63e

Prefix all CSS variables inside preflight

ec02aa7

Ensure fallbacks are emitted as CSS variables too

dfc21a7

Update change log

82a76ec

Handle --theme(…, initial) when encountered by an `--theme(…, fallb…

932633b

…ack)` call

Don't inject the fallback if the injected fallback is initial

31036ca

Update tests

2f50ecd

philipp-spiess force-pushed the chore/--theme-as-var branch from c32833a to 2f50ecd Compare March 17, 2025 14:46

thecrypticace reviewed Mar 17, 2025

View reviewed changes

thecrypticace suggested changes Mar 17, 2025

View reviewed changes

Fixes

feb93a9

philipp-spiess requested a review from thecrypticace March 18, 2025 10:40

thecrypticace approved these changes Mar 18, 2025

View reviewed changes

Merge branch 'main' into chore/--theme-as-var

14c2ee9

philipp-spiess force-pushed the chore/--theme-as-var branch from b775e6a to 14c2ee9 Compare March 19, 2025 09:34

Fix snaps

50ab909

philipp-spiess merged commit ca7b10e into main Mar 20, 2025
5 of 6 checks passed

philipp-spiess deleted the chore/--theme-as-var branch March 20, 2025 11:51

wongjn mentioned this pull request Mar 24, 2025

CSS Generation Issue between v4.0.14 and v4.0.15 in TailwindCSS #17346

Closed

fossabot bot mentioned this pull request Oct 25, 2025

chore(deps-dev): bump tailwindcss from 3.4.18 to 4.1.16 WhizUs-Labs/kcd-showcase-trw-demo-app#28

Closed

Uh oh!

Conversation

philipp-spiess commented Mar 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test plan

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thecrypticace left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

philipp-spiess commented Mar 7, 2025 •

edited

Loading