Add build plugins to inject design token fallbacks

Author: mirka

package-lock.json

@@ -43,6 +43,21 @@
 			"import": "./build-module/prebuilt/js/design-tokens.mjs",
 			"default": "./build/prebuilt/js/design-tokens.cjs"
 		},
+		"./postcss-plugins/postcss-ds-token-fallbacks": {
+			"types": "./src/postcss-plugins/postcss-ds-token-fallbacks.d.mts",
+			"import": "./src/postcss-plugins/postcss-ds-token-fallbacks.mjs",
+			"default": "./src/postcss-plugins/postcss-ds-token-fallbacks.mjs"
+		},
+		"./esbuild-plugins/esbuild-ds-token-fallbacks": {
+			"types": "./src/esbuild-plugins/esbuild-ds-token-fallbacks.d.mts",
+			"import": "./src/esbuild-plugins/esbuild-ds-token-fallbacks.mjs",
+			"default": "./src/esbuild-plugins/esbuild-ds-token-fallbacks.mjs"
+		},
+		"./vite-plugins/vite-ds-token-fallbacks": {
+			"types": "./src/vite-plugins/vite-ds-token-fallbacks.d.mts",
+			"import": "./src/vite-plugins/vite-ds-token-fallbacks.mjs",
+			"default": "./src/vite-plugins/vite-ds-token-fallbacks.mjs"
+		},
 		"./stylelint-plugins/no-unknown-ds-tokens": {
 			"types": "./build-types/stylelint-plugins/no-unknown-ds-tokens.d.ts",
 			"import": "./src/stylelint-plugins/no-unknown-ds-tokens.mjs",

packages/theme/package.json

@@ -0,0 +1,4 @@
+import type { Plugin } from 'esbuild';
+
+declare const plugin: Plugin;
+export default plugin;

packages/theme/src/esbuild-plugins/esbuild-ds-token-fallbacks.d.mts

@@ -0,0 +1,44 @@
+import { readFile } from 'fs/promises';
+import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';
+
+const LOADER_MAP = {
+	'.js': 'jsx',
+	'.jsx': 'jsx',
+	'.ts': 'tsx',
+	'.tsx': 'tsx',
+	'.mjs': 'jsx',
+};
+
+/**
+ * esbuild plugin that injects design-system token fallbacks into JS/TS files.
+ *
+ * Replaces bare `var(--wpds-*)` references in string literals with
+ * `var(--wpds-*, <fallback>)` so components render correctly without
+ * a ThemeProvider.
+ */
+const plugin = {
+	name: 'ds-token-fallbacks-js',
+	setup( build ) {
+		build.onLoad( { filter: /\.[mc]?[jt]sx?$/ }, async ( args ) => {
+			// Skip node_modules.
+			if ( args.path.includes( 'node_modules' ) ) {
+				return undefined;
+			}
+
+			const source = await readFile( args.path, 'utf8' );
+
+			if ( ! source.includes( '--wpds-' ) ) {
+				return undefined;
+			}
+
+			const ext = args.path.match( /(\.[^.]+)$/ )?.[ 1 ] || '.js';
+
+			return {
+				contents: addFallbackToVar( source ),
+				loader: LOADER_MAP[ ext ] || 'jsx',
+			};
+		} );
+	},
+};
+
+export default plugin;

packages/theme/src/esbuild-plugins/esbuild-ds-token-fallbacks.mjs

@@ -0,0 +1,4 @@
+import type { PluginCreator } from 'postcss';
+
+declare const plugin: PluginCreator<never>;
+export default plugin;

packages/theme/src/postcss-plugins/postcss-ds-token-fallbacks.d.mts

@@ -0,0 +1,16 @@
+import { addFallbackToVar } from './ds-token-fallbacks.mjs';
+
+const plugin = () => ( {
+	postcssPlugin: 'postcss-ds-token-fallbacks',
+	/** @param {import('postcss').Declaration} decl */
+	Declaration( decl ) {
+		const updated = addFallbackToVar( decl.value );
+		if ( updated !== decl.value ) {
+			decl.value = updated;
+		}
+	},
+} );
+
+plugin.postcss = true;
+
+export default plugin;

packages/theme/src/postcss-plugins/postcss-ds-token-fallbacks.mjs

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+
+declare const plugin: () => Plugin;
+export default plugin;

packages/theme/src/vite-plugins/vite-ds-token-fallbacks.d.mts

@@ -0,0 +1,23 @@
+import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs';
+
+/**
+ * Vite plugin that injects design-system token fallbacks into JS/TS files.
+ *
+ * Replaces bare `var(--wpds-*)` references in string literals with
+ * `var(--wpds-*, <fallback>)` so components render correctly without
+ * a ThemeProvider.
+ */
+const plugin = () => ( {
+	name: 'ds-token-fallbacks-js',
+	transform( code, id ) {
+		if ( ! /\.[mc]?[jt]sx?$/.test( id ) ) {
+			return null;
+		}
+		if ( ! code.includes( '--wpds-' ) ) {
+			return null;
+		}
+		return addFallbackToVar( code );
+	},
+} );
+
+export default plugin;

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

@@ -21,6 +21,26 @@ import babel from 'esbuild-plugin-babel';
 import { camelCase } from 'change-case';
 import { NodePackageImporter } from 'sass-embedded';
 
+// Optional dependency: @wordpress/theme provides plugins that inject fallback
+// values for design system tokens. Fails gracefully when the package is not
+// installed (it is an optional peerDependency).
+let dsTokenFallbacks;
+let dsTokenFallbacksJs;
+try {
+	const { default: postcssPlugin } = await import(
+		// eslint-disable-next-line import/no-unresolved
+		'@wordpress/theme/postcss-plugins/postcss-ds-token-fallbacks'
+	);
+	const { default: esbuildPlugin } = await import(
+		// eslint-disable-next-line import/no-unresolved
+		'@wordpress/theme/esbuild-plugins/esbuild-ds-token-fallbacks'
+	);
+	dsTokenFallbacks = postcssPlugin;
+	dsTokenFallbacksJs = esbuildPlugin;
+} catch {
+	// @wordpress/theme is optional; skip token fallbacks if not available.
+}
+
 /**
  * Internal dependencies
  */
@@ -150,8 +170,9 @@ function compileInlineStyle( { cssModules = false, minify = true } = {} ) {
 
 		let moduleExports = null;
 
-		// Transform the code: CSS modules and minification.
+		// Transform the code: token fallbacks, CSS modules and minification.
 		const plugins = [
+			dsTokenFallbacks,
 			cssModules &&
 				postcssModules( {
 					generateScopedName: '[contenthash]__[local]',
@@ -1242,6 +1263,7 @@ async function transpilePackage( packageName ) {
 		},
 	};
 	const plugins = [
+		dsTokenFallbacksJs,
 		needsEmotionPlugin && emotionPlugin,
 		wasmInlinePlugin,
 		externalizeAllExceptCssPlugin,

packages/wp-build/lib/build.mjs

@@ -6,6 +6,8 @@ import {
 } from 'vite';
 import react from '@vitejs/plugin-react';
 import type { StorybookConfig } from '@storybook/react-vite';
+import dsTokenFallbacks from '@wordpress/theme/postcss-plugins/postcss-ds-token-fallbacks';
+import dsTokenFallbacksJs from '@wordpress/theme/vite-plugins/vite-ds-token-fallbacks';
 
 const { NODE_ENV = 'development' } = process.env;
 
@@ -77,6 +79,7 @@ const config: StorybookConfig = {
 	viteFinal: async ( viteConfig ) => {
 		return mergeConfig( viteConfig, {
 			plugins: [
+				dsTokenFallbacksJs(),
 				react( {
 					jsxImportSource: '@emotion/react',
 					babel: {
@@ -174,6 +177,13 @@ const config: StorybookConfig = {
 					NODE_ENV === 'development'
 				),
 			},
+			css: {
+				postcss: {
+					// Vite bundles its own PostCSS, creating a deep
+					// type incompatibility with the top-level PostCSS.
+					plugins: [ dsTokenFallbacks as any ],
+				},
+			},
 			optimizeDeps: {
 				esbuildOptions: {
 					loader: {