feat(theming): add OS-adaptive auto themes (sap_horizon_auto, sap_horizon_hc_auto) (#13300)

ilhan007 · pskelin · web-flow · commit f6ae2b53ff86 · 2026-03-19T20:49:35.000+02:00
* feat(theming): add sap_horizon_auto and sap_fiori_3_auto OS-adaptive themes

Add auto-switching themes that adapt to the user's OS light/dark preference
using CSS light-dark() for color values and space toggles for non-color values.

At build time, the light and dark theme CSS outputs are merged into a single
stylesheet. Color variables use the native CSS light-dark() function (Chrome 123+,
Firefox 120+, Safari 17.5+). Non-color variables use the space toggle pattern
with guaranteed-invalid custom properties, the same approach already used for
cozy/compact density switching.

The auto theme is self-contained: switching away from it removes the toggles.
No runtime code changes needed — it is purely CSS-driven.

Usage:
- URL: ?sap-ui-theme=sap_horizon_auto
- JS: setTheme("sap_horizon_auto")
- Config: &lt;script data-ui5-config&gt;{"theme":"sap_horizon_auto"}&lt;/script&gt;

* feat(theming): add sap_horizon_hc_auto and sap_fiori_3_hc_auto OS-adaptive themes

Merge HCW (light) and HCB (dark) high contrast themes using the same
light-dark() and space toggle mechanism as the existing auto themes,
enabling automatic switching based on OS prefers-color-scheme.

* refactor(theming): remove fiori_3 auto themes, keep horizon only

Remove sap_fiori_3_auto and sap_fiori_3_hc_auto to reduce scope.
Only sap_horizon_auto and sap_horizon_hc_auto are generated.

---------

Co-authored-by: Petar Skelin &lt;petar.skelin@sap.com&gt;
diff --git a/packages/ai/src/themes/sap_horizon_auto/parameters-bundle.css b/packages/ai/src/themes/sap_horizon_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon (light) and sap_horizon_dark */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon/parameters-bundle.css";
diff --git a/packages/ai/src/themes/sap_horizon_hc_auto/parameters-bundle.css b/packages/ai/src/themes/sap_horizon_hc_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon_hcw (light) and sap_horizon_hcb (dark) */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon_hcw/parameters-bundle.css";
diff --git a/packages/compat/src/themes/sap_horizon_auto/parameters-bundle.css b/packages/compat/src/themes/sap_horizon_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon (light) and sap_horizon_dark */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon/parameters-bundle.css";
diff --git a/packages/compat/src/themes/sap_horizon_hc_auto/parameters-bundle.css b/packages/compat/src/themes/sap_horizon_hc_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon_hcw (light) and sap_horizon_hcb (dark) */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon_hcw/parameters-bundle.css";
diff --git a/packages/fiori/src/themes/sap_horizon_auto/parameters-bundle.css b/packages/fiori/src/themes/sap_horizon_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon (light) and sap_horizon_dark */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon/parameters-bundle.css";
diff --git a/packages/fiori/src/themes/sap_horizon_hc_auto/parameters-bundle.css b/packages/fiori/src/themes/sap_horizon_hc_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon_hcw (light) and sap_horizon_hcb (dark) */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon_hcw/parameters-bundle.css";
diff --git a/packages/main/src/themes/sap_horizon_auto/parameters-bundle.css b/packages/main/src/themes/sap_horizon_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon (light) and sap_horizon_dark */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon/parameters-bundle.css";
diff --git a/packages/main/src/themes/sap_horizon_hc_auto/parameters-bundle.css b/packages/main/src/themes/sap_horizon_hc_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon_hcw (light) and sap_horizon_hcb (dark) */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon_hcw/parameters-bundle.css";
diff --git a/packages/theming/src/themes/sap_horizon_auto/parameters-bundle.css b/packages/theming/src/themes/sap_horizon_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon (light) and sap_horizon_dark */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon/parameters-bundle.css";
diff --git a/packages/theming/src/themes/sap_horizon_hc_auto/parameters-bundle.css b/packages/theming/src/themes/sap_horizon_hc_auto/parameters-bundle.css
@@ -0,0 +1,3 @@
+/* Auto-generated at build time by merging sap_horizon_hcw (light) and sap_horizon_hcb (dark) */
+/* This placeholder enables directory detection by the theme loader generator */
+@import "../sap_horizon_hcw/parameters-bundle.css";
diff --git a/packages/tools/assets-meta.js b/packages/tools/assets-meta.js
@@ -6,10 +6,12 @@ const assetsMeta = {
       "sap_fiori_3_dark",
       "sap_fiori_3_hcb",
       "sap_fiori_3_hcw",
-	    "sap_horizon",
-	    "sap_horizon_dark",
-	    "sap_horizon_hcb",
-	    "sap_horizon_hcw",
+      "sap_horizon",
+      "sap_horizon_auto", // os-based auto theme, not generated by merging light + dark
+      "sap_horizon_dark",
+      "sap_horizon_hc_auto", // os-based auto theme, merging hcb + hcw
+      "sap_horizon_hcb",
+      "sap_horizon_hcw",
     ],
   },
   "languages": {
diff --git a/packages/tools/lib/css-processors/css-processor-themes.mjs b/packages/tools/lib/css-processors/css-processor-themes.mjs
@@ -8,8 +8,18 @@ import combineDuplicatedSelectors from "../postcss-combine-duplicated-selectors/
 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";
@@ -18,9 +28,14 @@ const generate = async (argv) => {
     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 = "") => {
@@ -38,6 +53,8 @@ const generate = async (argv) => {
         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, { from: undefined });
@@ -73,17 +90,54 @@ const generate = async (argv) => {
         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 { css } = f.path.includes("packages/theming") ? await processThemingPackageFile(f) : await processComponentPackageFile(f);
+            build.onEnd(async (result) => {
+                const processedCSS = new Map();
+
+                // Process all real theme files
+                await Promise.all(result.outputFiles.map(async f => {
+                    let { css } = isThemingPackage(f.path) ? await processThemingPackageFile(f) : await processComponentPackageFile(f);
+
+                    await saveFiles(f.path, css);
+                    processedCSS.set(f.path, css);
+                }));
 
-                    saveFiles(f.path, css);
-                });
+                // Generate auto themes by merging light + dark
+                await generateAutoThemes(processedCSS);
             })
         },
     }
@@ -110,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
-}
+}
diff --git a/packages/tools/lib/css-processors/merge-light-dark.mjs b/packages/tools/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 };

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+/* Auto-generated at build time by merging sap_horizon (light) and sap_horizon_dark */`
	`2`	`+/* This placeholder enables directory detection by the theme loader generator */`
	`3`	`+@import "../sap_horizon/parameters-bundle.css";`