Make `--theme(…)` return CSS variables #17036

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

@@ -51,15 +54,50 @@ function spacing(designSystem: DesignSystem, value: string, ...rest: string[]) {
  return `calc(${multiplier} * ${value})`
 }

-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

@@ -29,7 +29,7 @@ export type DesignSystem = {
  compileAstNodes(candidate: Candidate): ReturnType<typeof compileAstNodes>

  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

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 requested 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make `--theme(…)` return CSS variables #17036

Make `--theme(…)` return CSS variables #17036

philipp-spiess commented Mar 7, 2025 •

edited

Loading

philipp-spiess Mar 7, 2025

philipp-spiess Mar 7, 2025

philipp-spiess Mar 10, 2025

thecrypticace Mar 17, 2025

philipp-spiess Mar 18, 2025

thecrypticace Mar 17, 2025

philipp-spiess Mar 18, 2025

thecrypticace Mar 18, 2025

thecrypticace Mar 17, 2025

philipp-spiess Mar 18, 2025

thecrypticace left a comment

Make --theme(…) return CSS variables #17036

Are you sure you want to change the base?

Make --theme(…) return CSS variables #17036

Conversation

philipp-spiess commented Mar 7, 2025 • edited Loading

Test plan

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thecrypticace left a comment

Choose a reason for hiding this comment

Make `--theme(…)` return CSS variables #17036

Make `--theme(…)` return CSS variables #17036

philipp-spiess commented Mar 7, 2025 •

edited

Loading