Theme: add LightningCSS WPDS token fallback plugin

packages/theme/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Enhancements
 
+-   Add a Lightning CSS visitor plugin that injects design system token fallbacks, available as `@wordpress/theme/lightningcss-plugins/lightningcss-ds-token-fallbacks`, with an optional peer range of `>=1.19.0 <2.0.0` ([#80401](https://github.com/WordPress/gutenberg/pull/80401)).
 -   Widen optional peer dependency ranges so projects on newer tooling can install without peer resolution conflicts: Vite `^7 || ^8`, Stylelint `^16 || ^17`, and esbuild `>=0.27.2 <1.0.0` ([#80267](https://github.com/WordPress/gutenberg/pull/80267)).
 
 ### Documentation

packages/theme/README.md

@@ -244,11 +244,12 @@ The build plugins inject generated fallbacks into bare `var(--wpds-*)` reference
 
 `@wordpress/build` already applies these plugins automatically when `@wordpress/theme` is installed. You only need to configure them manually for custom build setups.
 
-| Export                                                        | Tool    | Scope |
-| ------------------------------------------------------------- | ------- | ----- |
-| `@wordpress/theme/postcss-plugins/postcss-ds-token-fallbacks` | PostCSS | CSS   |
-| `@wordpress/theme/esbuild-plugins/esbuild-ds-token-fallbacks` | esbuild | JS/TS |
-| `@wordpress/theme/vite-plugins/vite-ds-token-fallbacks`       | Vite    | JS/TS |
+| Export                                                                  | Tool          | Scope |
+| ----------------------------------------------------------------------- | ------------- | ----- |
+| `@wordpress/theme/postcss-plugins/postcss-ds-token-fallbacks`           | PostCSS       | CSS   |
+| `@wordpress/theme/lightningcss-plugins/lightningcss-ds-token-fallbacks` | Lightning CSS | CSS   |
+| `@wordpress/theme/esbuild-plugins/esbuild-ds-token-fallbacks`           | esbuild       | JS/TS |
+| `@wordpress/theme/vite-plugins/vite-ds-token-fallbacks`                 | Vite          | JS/TS |
 
 Existing fallbacks are unchanged. An unknown token in a bare reference fails the build.
 
@@ -263,6 +264,21 @@ export default {
 };
 ```
 
+### Lightning CSS
+
+```js
+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 ] ),
+} );
+```
+
+> **Note:** CSS Modules [`from global`](https://lightningcss.dev/css-modules.html#local-css-variables) references (for example `var(--wpds-dimension-gap-sm from global)` with `cssModules.dashedIdents`) are not yet supported. The visitor rebuilds `var()` from the token name alone, so `from` metadata is dropped and global custom properties may be incorrectly hashed.
+
 ### esbuild
 
 ```js

packages/theme/lightningcss-plugins/lightningcss-ds-token-fallbacks.mjs

@@ -0,0 +1,32 @@
+import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';
+
+/**
+ * Lightning CSS visitor that injects design-system token fallbacks into CSS.
+ *
+ * Replaces bare `var(--wpds-*)` references with `var(--wpds-*, <fallback>)`.
+ *
+ * Existing fallbacks are left untouched. Unknown tokens throw.
+ *
+ * @type {import('lightningcss').Visitor<never>}
+ */
+const plugin = {
+	/** @param {import('lightningcss').Variable} variable */
+	Variable( variable ) {
+		// Leave existing fallbacks alone, including the valid empty fallback
+		// form `var(--token,)` which Lightning CSS parses as `fallback: []`.
+		if ( variable.fallback !== null ) {
+			return;
+		}
+
+		const tokenName = variable.name.ident;
+		if ( ! tokenName.startsWith( '--wpds-' ) ) {
+			return;
+		}
+
+		return {
+			raw: addFallbackToVar( `var(${ tokenName })` ),
+		};
+	},
+};
+
+export default plugin;