@ui5/webcomponents-tools 0.0.0-47cc17a26 → 0.0.0-49bade48d

package/lib/cem/validate.js

@@ -5,6 +5,7 @@ const path = require('path');
 const extenalSchema = require('./schema.json');
 const internalSchema = require('./schema-internal.json');
 
+const isVerbose = () => process.env.UI5_VERBOSE === "true";
 
 const validateFn = async () => {
 	// Load your JSON data from the input file
@@ -49,7 +50,9 @@ const validateFn = async () => {
 	// Validate the JSON data against the schema
 	if (devMode) {
 		if (validate(inputDataInternal)) {
-			console.log('Internal custom  element manifest is validated successfully');
+			if (isVerbose()) {
+				console.log('Internal custom element manifest is validated successfully');
+			}
 		} else {
 			console.log(validate.errors)
 			throw new Error(`Validation of internal custom elements manifest failed: ${validate.errors}`);
@@ -61,7 +64,9 @@ const validateFn = async () => {
 
 	// Validate the JSON data against the schema
 	if (validate(inputDataExternal)) {
-		console.log('Custom element manifest is validated successfully');
+		if (isVerbose()) {
+			console.log('Custom element manifest is validated successfully');
+		}
 		fs.writeFileSync(inputFilePath, JSON.stringify(inputDataExternal, null, 2), 'utf8');
 		fs.writeFileSync(inputFilePath.replace("custom-elements", "custom-elements-internal"), JSON.stringify(inputDataInternal, null, 2), 'utf8');
 	} else if (devMode) {

package/lib/chokidar/chokidar.js

@@ -0,0 +1,28 @@
+const chokidar = require('chokidar');
+const { exec } = require("child_process");
+
+const main = async (argv) => {
+	if (argv.length < 4) {
+		console.error("Please provide a file pattern to watch and a command to execute on changes.");
+		console.error("<file-pattern> <command>");
+		process.exit(1);
+	}
+
+	const filePattern = argv[2];
+	const command = argv.slice(3).join(' ');
+
+	const watcher = new chokidar.FSWatcher();
+
+	watcher.add(filePattern);
+	watcher.unwatch("src/generated");
+
+	watcher.on('change', async () => {
+		exec(command);
+	});
+};
+
+if (require.main === module) {
+	main(process.argv)
+}
+
+exports._ui5mainFn = main;

package/lib/copy-and-watch/index.js

@@ -42,6 +42,11 @@ const copyAndWatchFn = async (argv) => {
 		}
 	});
 
+	// Default to silent mode unless verbose is enabled
+	if (process.env.UI5_VERBOSE !== "true") {
+		options.silent = true;
+	}
+
 	if (args.length < 2) {
 		console.error('Not enough arguments: copy-and-watch [options] <sources> <target>');
 		process.exit(1);

package/lib/copy-list/index.js

@@ -22,7 +22,9 @@ const generate = async (argv) => {
 	});
 
 	return Promise.all(promises).then(() => {
-		console.log("Files copied.");
+		if (process.env.UI5_VERBOSE === "true") {
+			console.log("Files copied.");
+		}
 	});
 };
 

package/lib/create-icons/index.js

@@ -1,40 +1,42 @@
 const fs = require("fs").promises;
 const path = require("path");
 
-const iconTemplate = (name, pathData, ltr, collection, packageName) => `import { registerIcon } from "@ui5/webcomponents-base/dist/asset-registries/Icons.js";
+const iconTemplate = (name, pathData, ltr, viewBox, collection, packageName) => `import { registerIcon } from "@ui5/webcomponents-base/dist/asset-registries/Icons.js";
 
 const name = "${name}";
 const pathData = "${pathData}";
 const ltr = ${ltr};
 const accData = null;
+const viewBox = "${viewBox}";
 const collection = "${collection}";
 const packageName = "${packageName}";
 
-registerIcon(name, { pathData, ltr, collection, packageName });
+registerIcon(name, { pathData, ltr, viewBox, collection, packageName });
 
 export default "${collection}/${name}";
-export { pathData, ltr, accData };`;
+export { pathData, ltr, viewBox, accData };`;
 
 
-const iconAccTemplate = (name, pathData, ltr, accData, collection, packageName, versioned) => `import { registerIcon } from "@ui5/webcomponents-base/dist/asset-registries/Icons.js";
+const iconAccTemplate = (name, pathData, ltr, viewBox, accData, collection, packageName, versioned) => `import { registerIcon } from "@ui5/webcomponents-base/dist/asset-registries/Icons.js";
 import { ${accData.key} } from "${versioned ? "../" : "./"}generated/i18n/i18n-defaults.js";
 
 const name = "${name}";
 const pathData = "${pathData}";
 const ltr = ${ltr};
 const accData = ${accData.key};
+const viewBox = "${viewBox}";
 const collection = "${collection}";
 const packageName = "${packageName}";
 
-registerIcon(name, { pathData, ltr, accData, collection, packageName });
+registerIcon(name, { pathData, ltr, viewBox, accData, collection, packageName });
 
 export default "${collection}/${name}";
-export { pathData, ltr, accData };`;
+export { pathData, ltr, viewBox, accData };`;
 
 
 
 const collectionTemplate = (name, versions, fullName) => `import { isLegacyThemeFamilyAsync } from "@ui5/webcomponents-base/dist/config/Theme.js";
-import { pathData as pathData${versions[0]}, ltr, accData } from "./${versions[0]}/${name}.js";
+import { pathData as pathData${versions[0]}, ltr, viewBox, accData } from "./${versions[0]}/${name}.js";
 import { pathData as pathData${versions[1]} } from "./${versions[1]}/${name}.js";
 
 const getPathData = async() => {
@@ -42,27 +44,29 @@ const getPathData = async() => {
 };
 
 export default "${fullName}";
-export { getPathData, ltr, accData };`;
+export { getPathData, ltr, viewBox, accData };`;
 
 
 const typeDefinitionTemplate = (name, accData, collection) => `declare const pathData: string;
 declare const ltr: boolean;
+declare const viewBox: string;
 declare const accData: ${accData ? '{ key: string; defaultText: string; }' : null}
 declare const _default: "${collection}/${name}";
 
 export default _default;
-export { pathData, ltr, accData };`
+export { pathData, ltr, viewBox, accData };`
 
 const collectionTypeDefinitionTemplate = (name, accData) => `declare const getPathData: () => Promise<string>;
 declare const ltr: boolean;
+declare const viewBox: string;
 declare const accData: ${accData ? '{ key: string; defaultText: string; }' : null}
 declare const _default: "${name}";
 
 export default _default;
-export { getPathData, ltr, accData };`
+export { getPathData, ltr, viewBox, accData };`
 
 
-const svgTemplate = (pathData) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+const svgTemplate = (pathData, viewBox) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}">
 	<path d="${pathData}"/>
 </svg>`;
 
@@ -80,15 +84,16 @@ const createIcons = async (argv) => {
 		const iconData = json.data[name];
 		const pathData = iconData.path;
 		const ltr = !!iconData.ltr;
+		const viewBox = iconData.viewBox || "0 0 512 512";
 		const acc = iconData.acc;
 		const packageName = json.packageName;
 		const collection = json.collection;
 		const versioned = json.version;
 
-		const content = acc ? iconAccTemplate(name, pathData, ltr, acc, collection, packageName, versioned) : iconTemplate(name, pathData, ltr, collection, packageName);
+		const content = acc ? iconAccTemplate(name, pathData, ltr, viewBox, acc, collection, packageName, versioned) : iconTemplate(name, pathData, ltr, viewBox, collection, packageName);
 
 		promises.push(fs.writeFile(path.join(destDir, `${name}.js`), content));
-		promises.push(fs.writeFile(path.join(destDir, `${name}.svg`), svgTemplate(pathData)));
+		promises.push(fs.writeFile(path.join(destDir, `${name}.svg`), svgTemplate(pathData, viewBox)));
 		promises.push(fs.writeFile(path.join(destDir, `${name}.d.ts`), typeDefinitionTemplate(name, acc, collection)));
 
 		// For versioned icons collections, the script creates top level (unversioned) module that internally imports the versioned ones.

package/lib/create-illustrations/index.js

@@ -80,15 +80,38 @@ const generate = async (argv) => {
 	const fileNames = new Set();
 
 	let dotIllustrationNames = [];
+	let v5IllustrationNames = new Set();
 
 	try {
 		await fs.access(srcPath);
 	} catch (error) {
-		console.log(`The path ${srcPath} does not exist.`);
+		if (process.env.UI5_VERBOSE === "true") {
+			console.log(`The path ${srcPath} does not exist.`);
+		}
 		return Promise.resolve(null);
 	}
 
-	console.log(`Generating illustrations from ${srcPath} to ${destPath}`)
+	// For V4 TNT illustrations, check which ones have V5 versions available
+	// so we only register V5 loaders for illustrations that actually exist
+	if (collection === "V4" && illustrationSet === "tnt") {
+		const v5Path = srcPath.replace("/illustrations/", "/illustrations-v5/");
+		try {
+			const v5Files = await fs.readdir(path.normalize(v5Path));
+			const v5Pattern = new RegExp(`${illustrationsPrefix}-.+-(.+).svg`);
+			v5Files.forEach(file => {
+				const match = file.match(v5Pattern);
+				if (match) {
+					v5IllustrationNames.add(match[1]);
+				}
+			});
+		} catch (error) {
+			// V5 path doesn't exist, no V5 illustrations available
+		}
+	}
+
+	if (process.env.UI5_VERBOSE === "true") {
+		console.log(`Generating illustrations from ${srcPath} to ${destPath}`);
+	}
 
 	const svgImportTemplate = svgContent => {
 		return `export default \`${svgContent}\`;`
@@ -121,6 +144,23 @@ const generate = async (argv) => {
 		// If no Dot is present, Spot will be imported as Dot
 		const hasDot = dotIllustrationNames.indexOf(illustrationName) !== -1 ? 'Dot' : 'Spot';
 
+		// For V4 TNT illustrations that have V5 versions, register loaders for V5 and V5/HC
+		// so that when the illustration is imported directly (e.g., "@ui5/webcomponents-fiori/dist/illustrations/tnt/NoApplications.js")
+		// and Horizon themes are used, the correct V5 illustration is loaded dynamically.
+		// Note: Only TNT set has V5 illustrations, and not all TNT illustrations have V5 versions.
+		// The dynamic imports ensure that V5 SVGs are loaded lazily only when actually needed.
+		const hasV5Version = v5IllustrationNames.has(illustrationName);
+		const v5LoaderRegistration = collection === "V4" && illustrationSet === "tnt" && hasV5Version ? `
+import { registerIllustrationLoader } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
+
+registerIllustrationLoader("${illustrationSet}/V5/${illustrationName}", async function loadIllustrationV5() {
+	return (await import("../../illustrations-v5/${illustrationSet}/${illustrationName}.js")).default;
+});
+registerIllustrationLoader("${illustrationSet}/V5/HC/${illustrationName}", async function loadIllustrationV5HC() {
+	return (await import("../../illustrations-v5/${illustrationSet}/hc/${illustrationName}.js")).default;
+});
+` : '';
+
 		return `import { unsafeRegisterIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
 import dialogSvg from "./${illustrationsPrefix}-Dialog-${illustrationName}.js";
 import sceneSvg from "./${illustrationsPrefix}-Scene-${illustrationName}.js";
@@ -128,7 +168,7 @@ import spotSvg from "./${illustrationsPrefix}-Spot-${illustrationName}.js";
 import dotSvg from "./${illustrationsPrefix}-${hasDot}-${illustrationName}.js";${defaultText ? `import {
 	IM_TITLE_${illustrationNameUpperCase},
 	IM_SUBTITLE_${illustrationNameUpperCase},
-} from "../generated/i18n/i18n-defaults.js";` : ``}
+} from "../generated/i18n/i18n-defaults.js";` : ``}${v5LoaderRegistration}
 
 const name = "${illustrationName}";
 const set = "${illustrationSet}";
@@ -193,7 +233,9 @@ export { dialogSvg, sceneSvg, spotSvg, dotSvg };`
 			return Promise.all(nestedPromises);
 		})
 		.then(() => {
-			console.log("Illustrations generated.");
+			if (process.env.UI5_VERBOSE === "true") {
+				console.log("Illustrations generated.");
+			}
 		});
 };
 

package/lib/css-processors/css-processor-components.mjs

@@ -8,11 +8,15 @@ import scopeVariables from "./scope-variables.mjs";
 import { writeFileIfChanged, getFileContent } from "./shared.mjs";
 import { pathToFileURL } from "url";
 
+
 const generate = async (argv) => {
+    const CSS_VARIABLES_TARGET = process.env.CSS_VARIABLES_TARGET === "host";
     const tsMode = process.env.UI5_TS === "true";
     const extension = tsMode ? ".css.ts" : ".css.js";
 
-    const packageJSON = JSON.parse(fs.readFileSync("./package.json"))
+    const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
+    const basePackageJSON = (await import("@ui5/webcomponents-base/package.json", { with: { type: "json" } })).default;
+
     const inputFilesGlob = "src/themes/*.css";
     const restArgs = argv.slice(2);
 
@@ -23,8 +27,15 @@ const generate = async (argv) => {
 
             build.onEnd(result => {
                 result.outputFiles.forEach(async f => {
-                    // scoping
-                    let newText = scopeVariables(f.text, packageJSON);
+                    let newText
+
+                    if (CSS_VARIABLES_TARGET) {
+                        newText = f.text;
+                    } else {
+                        // scoping
+                        newText = scopeVariables(f.text, basePackageJSON);
+                    }
+
                     newText = newText.replaceAll(/\\/g, "\\\\"); // Escape backslashes as they might appear in css rules
                     await mkdir(path.dirname(f.path), { recursive: true });
                     writeFile(f.path, newText);

package/lib/css-processors/css-processor-themes.mjs

@@ -5,24 +5,59 @@ import * as path from "path";
 import { writeFile, mkdir } from "fs/promises";
 import postcss from "postcss";
 import combineDuplicatedSelectors from "../postcss-combine-duplicated-selectors/index.js"
+import postcssPlugin from "./postcss-plugin.mjs";
 import { writeFileIfChanged, getFileContent } from "./shared.mjs";
 import scopeVariables from "./scope-variables.mjs";
+import { mergeLightDark } from "./merge-light-dark.mjs";
 import { pathToFileURL } from "url";
 
+/**
+ * Auto theme pairs: each entry defines a light theme, its dark counterpart,
+ * and the auto theme name that will be generated by merging them.
+ */
+const AUTO_THEME_PAIRS = [
+    { light: "sap_horizon", dark: "sap_horizon_dark", auto: "sap_horizon_auto" },
+    { light: "sap_horizon_hcw", dark: "sap_horizon_hcb", auto: "sap_horizon_hc_auto" },
+];
+
 const generate = async (argv) => {
+    const CSS_VARIABLES_TARGET = process.env.CSS_VARIABLES_TARGET === "host";
     const tsMode = process.env.UI5_TS === "true";
     const extension = tsMode ? ".css.ts" : ".css.js";
 
-    const packageJSON = JSON.parse(fs.readFileSync("./package.json"))
+    const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
+    const basePackageJSON = (await import("@ui5/webcomponents-base/package.json", { with: { type: "json" } })).default;
 
-    const inputFiles = await globby([
+    const allInputFiles = await globby([
         "src/**/parameters-bundle.css",
     ]);
+
+    // Filter out auto theme placeholders - they will be generated from merging light + dark
+    const autoThemeNames = AUTO_THEME_PAIRS.map(p => p.auto);
+    const inputFiles = allInputFiles.filter(f => !autoThemeNames.some(name => f.includes(`/${name}/`)));
+
     const restArgs = argv.slice(2);
 
+    const saveFiles = async (distPath, css, suffix = "") => {
+        await mkdir(path.dirname(distPath), { recursive: true });
+        writeFile(distPath.replace(".css", suffix + ".css"), css);
+
+        // JSON
+        const jsonPath = distPath.replace(/dist[\/\\]css/, "dist/generated/assets").replace(".css", suffix + ".css.json");
+        await mkdir(path.dirname(jsonPath), { recursive: true });
+        writeFileIfChanged(jsonPath, JSON.stringify(css));
+
+        // JS/TS
+        const jsPath = distPath.replace(/dist[\/\\]css/, "src/generated/").replace(".css", suffix + extension);
+        const jsContent = getFileContent(packageJSON.name, "\`" + css + "\`");
+        writeFileIfChanged(jsPath, jsContent);
+    }
+
+    const isThemingPackage = (filePath) => filePath.includes("packages/theming") || filePath.includes("packages\\theming");
+
     const processThemingPackageFile = async (f) => {
         const selector = ':root';
-        const result = await postcss().process(f.text);
+        const result = await postcss().process(f.text, { from: undefined });
 
         const newRule = postcss.rule({ selector });
 
@@ -34,37 +69,75 @@ const generate = async (argv) => {
             });
         });
 
-        return newRule.toString();
+        return { css: newRule.toString() };
     };
 
     const processComponentPackageFile = async (f) => {
-        const result = await postcss(combineDuplicatedSelectors).process(f.text);
+        if (CSS_VARIABLES_TARGET) {
+            const result = await postcss([
+                combineDuplicatedSelectors,
+                postcssPlugin
+            ]).process(f.text, { from: undefined });
+
+            return { css: result.css };
+        }
 
-        return scopeVariables(result.css, packageJSON, f.path);
+
+        const combined = await postcss([
+            combineDuplicatedSelectors,
+        ]).process(f.text, { from: undefined });
+
+        return { css: scopeVariables(combined.css, basePackageJSON, f.path) };
     }
 
+    /**
+     * Generate auto theme CSS by merging light and dark theme outputs.
+     * For the theming package (:root), adds color-scheme and toggle variables.
+     * For component packages (:host), just merges the variables.
+     */
+    const generateAutoThemes = async (processedCSS) => {
+        for (const { light, dark, auto } of AUTO_THEME_PAIRS) {
+            for (const [lightPath, lightCSS] of processedCSS) {
+                // Match paths containing the light theme folder
+                const lightPattern = new RegExp(`[/\\\\]${light}[/\\\\]`);
+                if (!lightPattern.test(lightPath)) continue;
+
+                const darkPath = lightPath.replace(lightPattern, (match) => match.replace(light, dark));
+                const darkCSS = processedCSS.get(darkPath);
+                if (!darkCSS) continue;
+
+                const selector = isThemingPackage(lightPath) ? ":root" : ":host";
+                let autoCSS = mergeLightDark(lightCSS, darkCSS, selector);
+
+                // For the theming package, add color-scheme and toggle setup
+                if (selector === ":root") {
+                    autoCSS = addAutoThemeSetup(autoCSS);
+                }
+
+                const autoPath = lightPath.replace(lightPattern, (match) => match.replace(light, auto));
+                await saveFiles(autoPath, autoCSS);
+            }
+        }
+    };
+
     let scopingPlugin = {
         name: 'scoping',
         setup(build) {
             build.initialOptions.write = false;
 
-            build.onEnd(result => {
-                result.outputFiles.forEach(async f => {
-                    let newText = f.path.includes("packages/theming") ? await processThemingPackageFile(f) : await processComponentPackageFile(f);
+            build.onEnd(async (result) => {
+                const processedCSS = new Map();
 
-                    await mkdir(path.dirname(f.path), { recursive: true });
-                    writeFile(f.path, newText);
+                // Process all real theme files
+                await Promise.all(result.outputFiles.map(async f => {
+                    let { css } = isThemingPackage(f.path) ? await processThemingPackageFile(f) : await processComponentPackageFile(f);
 
-                    // JSON
-                    const jsonPath = f.path.replace(/dist[\/\\]css/, "dist/generated/assets").replace(".css", ".css.json");
-                    await mkdir(path.dirname(jsonPath), { recursive: true });
-                    writeFileIfChanged(jsonPath, JSON.stringify(newText));
+                    await saveFiles(f.path, css);
+                    processedCSS.set(f.path, css);
+                }));
 
-                    // JS/TS
-                    const jsPath = f.path.replace(/dist[\/\\]css/, "src/generated/").replace(".css", extension);
-                    const jsContent = getFileContent(packageJSON.name, "\`" + newText + "\`");
-                    writeFileIfChanged(jsPath, jsContent);
-                });
+                // Generate auto themes by merging light + dark
+                await generateAutoThemes(processedCSS);
             })
         },
     }
@@ -75,6 +148,7 @@ const generate = async (argv) => {
         minify: true,
         outdir: 'dist/css',
         outbase: 'src',
+        logLevel: process.env.UI5_VERBOSE === "true" ? "warning" : "error",
         plugins: [
             scopingPlugin,
         ],
@@ -90,13 +164,63 @@ const generate = async (argv) => {
     }
 }
 
+/**
+ * Adds auto theme setup CSS: color-scheme declaration and
+ * light/dark toggle variables with @media switching.
+ *
+ * In light mode (default):
+ *   --_ui5-light-scheme is guaranteed-invalid → var() fallbacks resolve to light values
+ *   --_ui5-dark-scheme is valid empty → var() fallbacks are NOT used
+ *
+ * In dark mode (@media prefers-color-scheme: dark):
+ *   --_ui5-light-scheme is valid empty → var() fallbacks are NOT used
+ *   --_ui5-dark-scheme is guaranteed-invalid → var() fallbacks resolve to dark values
+ *
+ * @param {string} mergedCSS - The merged :root CSS from mergeLightDark()
+ * @returns {string} CSS with toggle setup and @media rule appended
+ */
+const addAutoThemeSetup = (mergedCSS) => {
+    const root = postcss.parse(mergedCSS);
+
+    // Add color-scheme and toggle defaults to the :root rule
+    root.walkRules(":root", rule => {
+        rule.prepend(
+            postcss.decl({ prop: "--_ui5-dark-scheme", value: " " }),
+        );
+        rule.prepend(
+            postcss.decl({ prop: "--_ui5-light-scheme", value: "var(--_ui5-f2d95f8)" }),
+        );
+        rule.prepend(
+            postcss.decl({ prop: "color-scheme", value: "light dark" }),
+        );
+    });
+
+    // Add @media rule for dark mode - flips the toggles
+    const mediaRule = postcss.atRule({
+        name: "media",
+        params: "(prefers-color-scheme: dark)",
+    });
+    const darkRoot = postcss.rule({ selector: ":root" });
+    darkRoot.append(
+        postcss.decl({ prop: "--_ui5-light-scheme", value: " " }),
+        postcss.decl({ prop: "--_ui5-dark-scheme", value: "var(--_ui5-f2d95f8)" }),
+        postcss.decl({ prop: "color-scheme", value: "dark" }),
+    );
+    mediaRule.append(darkRoot);
+    root.append(mediaRule);
+
+    return root.toString();
+};
+
 const filePath = process.argv[1];
-const fileUrl = pathToFileURL(filePath).href;
 
-if (import.meta.url === fileUrl) {
-    generate(process.argv)
+if (filePath) {
+    const fileUrl = pathToFileURL(filePath).href;
+    if (import.meta.url === fileUrl) {
+        generate(process.argv)
+    }
 }
 
 export default {
     _ui5mainFn: generate
-}
+}

package/lib/css-processors/merge-light-dark.mjs

@@ -0,0 +1,131 @@
+import postcss from "postcss";
+
+/**
+ * Merges two CSS theme files (light and dark) into a single file using
+ * CSS light-dark() for color values and space toggles for non-color values.
+ *
+ * The space toggle pattern uses --_ui5-dark-scheme / --_ui5-light-scheme,
+ * following the same approach as the compact/cozy density toggles.
+ *
+ * @param {string} lightCSS - The light theme CSS string
+ * @param {string} darkCSS - The dark theme CSS string
+ * @param {string} selector - The selector to match (":root" for theming package, ":host" for component packages)
+ * @returns {string} Merged CSS string with light-dark() and space toggle values
+ */
+const mergeLightDark = (lightCSS, darkCSS, selector = ":root") => {
+	const lightRoot = postcss.parse(lightCSS);
+	const darkRoot = postcss.parse(darkCSS);
+
+	// Extract all custom property declarations from each theme
+	const lightVars = extractVars(lightRoot, selector);
+	const darkVars = extractVars(darkRoot, selector);
+
+	// Build merged declarations
+	const allProps = new Set([...lightVars.keys(), ...darkVars.keys()]);
+	const mergedRule = postcss.rule({ selector });
+
+	for (const prop of allProps) {
+		const lightVal = lightVars.get(prop);
+		const darkVal = darkVars.get(prop);
+
+		if (prop.startsWith("--sapThemeMetaData")) {
+			// Keep light version only for metadata
+			if (lightVal !== undefined) {
+				mergedRule.append(postcss.decl({ prop, value: lightVal }));
+			}
+			continue;
+		}
+
+		if (lightVal !== undefined && darkVal !== undefined) {
+			if (lightVal === darkVal) {
+				// Identical values - output once
+				mergedRule.append(postcss.decl({ prop, value: lightVal }));
+			} else if (isColorValue(lightVal) && isColorValue(darkVal)) {
+				// Different color values - use light-dark()
+				mergedRule.append(postcss.decl({ prop, value: `light-dark(${lightVal}, ${darkVal})` }));
+			} else {
+				// Different non-color values - use space toggle
+				mergedRule.append(postcss.decl({
+					prop,
+					value: `var(--_ui5-light-scheme, ${lightVal}) var(--_ui5-dark-scheme, ${darkVal})`,
+				}));
+			}
+		} else if (lightVal !== undefined) {
+			// Only in light theme - use space toggle with guaranteed-invalid for dark
+			mergedRule.append(postcss.decl({
+				prop,
+				value: `var(--_ui5-light-scheme, ${lightVal}) var(--_ui5-dark-scheme, var(--_ui5-f2d95f8))`,
+			}));
+		} else {
+			// Only in dark theme - use space toggle with guaranteed-invalid for light
+			mergedRule.append(postcss.decl({
+				prop,
+				value: `var(--_ui5-dark-scheme, ${darkVal}) var(--_ui5-light-scheme, var(--_ui5-f2d95f8))`,
+			}));
+		}
+	}
+
+	return mergedRule.toString();
+};
+
+/**
+ * Extract custom property declarations from a parsed CSS root for a given selector.
+ * @param {postcss.Root} root
+ * @param {string} selector
+ * @returns {Map<string, string>}
+ */
+const extractVars = (root, selector) => {
+	const vars = new Map();
+	root.walkRules(rule => {
+		if (rule.selector === selector) {
+			rule.walkDecls(decl => {
+				if (decl.prop.startsWith("--")) {
+					vars.set(decl.prop, decl.value);
+				}
+			});
+		}
+	});
+	return vars;
+};
+
+/**
+ * Heuristic to determine if a CSS value is a color value.
+ * light-dark() only works with <color> values.
+ */
+const isColorValue = (value) => {
+	const v = value.trim().toLowerCase();
+
+	// hex colors
+	if (/^#[0-9a-f]{3,8}$/.test(v)) return true;
+
+	// rgb/rgba/hsl/hsla functions
+	if (/^(rgba?|hsla?|oklch|oklab|lab|lch|color)\s*\(/.test(v)) return true;
+
+	// transparent and common CSS color keywords
+	if (v === "transparent" || v === "currentcolor") return true;
+
+	// Named CSS colors - check for common ones used in SAP themes
+	const namedColors = new Set([
+		"black", "white", "red", "green", "blue", "yellow", "orange", "purple",
+		"pink", "gray", "grey", "brown", "cyan", "magenta", "lime", "navy",
+		"teal", "aqua", "silver", "maroon", "olive", "fuchsia",
+	]);
+	if (namedColors.has(v)) return true;
+
+	// var() references to SAP color variables
+	// Match patterns like var(--sapXxxColor), var(--sapXxx_Background), etc.
+	if (/^var\(--sap\w*(Color|Background|BorderColor|TextColor|IconColor|ForegroundColor|HoverColor|ActiveColor|SelectedColor|Shadow)\w*\)$/.test(value.trim())) return true;
+
+	// Compound values containing color-related var() references
+	// e.g., "0.0625rem solid var(--sapContent_FocusColor)"
+	if (/var\(--sap\w*(Color|BorderColor|TextColor|IconColor|ForegroundColor|SelectedColor)\w*\)/.test(value)) {
+		// If the value also contains dimensional tokens, it's likely a shorthand (border, box-shadow)
+		// These are NOT pure color values - light-dark() won't work
+		if (/\d+(\.\d+)?(rem|px|em|%)/.test(value)) return false;
+		return true;
+	}
+
+	return false;
+};
+
+export { mergeLightDark, isColorValue };