Theme: add LightningCSS WPDS token fallback plugin

[simison]

Previous plugins added in:

• Theme: Add design token fallback generation #75586
• Theme: Add build plugins to inject design token fallbacks #75589

What?

• Adds LightningCSS plugin (or "visitor") in the theme package alongside the existing PostCSS, esbuild and Vite plugins.

  • Defines peer dependency as widely as possible (v2 doesn't exist, and v1.19.0 is the first with raw support used here). v1.32.0 is the current.

• Adds tests in all plugins for the "empty fallback" case; var( --wpds-example, ) to ensure we treat it equally in all plugins; no fallback gets injected and it's left empty.

Why?

Allows consumers to add WPDS token fallbacks when using LightningCSS without needing to implement workarounds or switch to PostCSS.

One group of consumers are tsdown users, since @tsdown/css relies on lightningcss by default, although the PostCSS processor is available with tsdown, too.

How?

Consumers would add the plugin to their configs:

Lightning CSS

import { transform, composeVisitors } from 'lightningcss';
import dsTokenFallbacks from '@wordpress/theme/lightningcss-plugins/lightningcss-ds-token-fallbacks';

const { code } = transform( {
	filename: 'styles.css',
	code: Buffer.from( css ),
	visitor: composeVisitors( [ dsTokenFallbacks ] ),
} );

tsdown

import lightningcssDsTokenFallbacks from '@wordpress/theme/lightningcss-plugins/lightningcss-ds-token-fallbacks';
import { defineConfig } from 'tsdown';

export default defineConfig( {
	// ...
	css: {
		fileName: 'styles.css',
		lightningcss: {
			visitor: lightningcssDsTokenFallbacks,
		},
	},
	// ...
} );

Testing Instructions

• Have a simple LightningCSS and/or tsdown setup with some WPDS tokens without fallbacks. (Should be trivial with AI but let me know if I can help)

• Link @wordpress/theme from your local Gutenberg

• Observe the built bundle has WPDS fallbacks

• Tests: npm run test:unit -- packages/theme

Testing Instructions for Keyboard

Use of AI Tools

yes

[github-actions]

Size Change: 0 B

Total Size: 7.73 MB

_{compressed-size-action}

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: simison <simison@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[simison]

Could be pulled from a shared location.

[simison]

Done elsewhere too currently, so better moved in a separate PR.

gutenberg/packages/theme/vite-plugins/vite-ds-token-fallbacks.mjs

Line 1 in 05026e2

import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';

[github-actions]

Flaky tests detected in 3d63dec.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29576112220
📝 Reported issues:

• [Flaky Test] should paste block styles using keyboard #78759 in /test/e2e/specs/editor/various/list-view.spec.js

[ciampo]

cc @mirka as the OG author of the fallback plugins.,

I gave the PR an initial AI-assisted review pass, but I don't have a lot of experise myself to review this in depth.

Could we get any LightningCSS consumers to test it out (instead of using only synthetic tests) ?

[simison]

Could we get any LightningCSS consumers to test it out (instead of using only synthetic tests) ?

Testing this at Automattic/jetpack#50614 — bundles this produces are identical with alternative PostCSS setup 🎉