feat: add ColorScheme API for light/dark theme support

flow-client/src/main/frontend/Flow.ts

@@ -539,6 +539,20 @@ export class Flow {
       params['v-np'] = ($wnd as any).navigator.platform;
     }
 
+    /* Color scheme from CSS color-scheme property */
+    const colorScheme = getComputedStyle(document.documentElement).colorScheme.trim();
+    // "normal" is the default value and means no color scheme is set
+    params['v-cs'] = colorScheme && colorScheme !== 'normal' ? colorScheme : '';
+    /* Theme name - detect which theme is in use */
+    const computedStyle = getComputedStyle(document.documentElement);
+    let themeName = '';
+    if (computedStyle.getPropertyValue('--vaadin-lumo-theme').trim()) {
+      themeName = 'lumo';
+    } else if (computedStyle.getPropertyValue('--vaadin-aura-theme').trim()) {
+      themeName = 'aura';
+    }
+    params['v-tn'] = themeName;
+
     /* Stringify each value (they are parsed on the server side) */
     const stringParams: Record<string, string> = {};
     Object.keys(params).forEach((key) => {

flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java

@@ -1362,7 +1362,7 @@ public ExtendedClientDetails getExtendedClientDetails() {
             // Create placeholder with default values
             extendedClientDetails = new ExtendedClientDetails(ui, null, null,
                     null, null, null, null, null, null, null, null, null, null,
-                    null, null, null, null);
+                    null, null, null, null, null, null);
         }
         return extendedClientDetails;
     }

flow-server/src/main/java/com/vaadin/flow/component/page/ColorScheme.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.component.page;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Defines the color scheme for the application using the CSS color-scheme
+ * property.
+ * <p>
+ * This annotation should be placed on a class that implements
+ * {@link com.vaadin.flow.component.page.AppShellConfigurator} to set the
+ * initial color scheme for the entire application.
+ * <p>
+ * Example usage:
+ *
+ * <pre>
+ * &#64;ColorScheme(ColorScheme.Value.DARK)
+ * public class AppShell implements AppShellConfigurator {
+ * }
+ * </pre>
+ * <p>
+ * The color scheme can also be changed programmatically at runtime using
+ * {@link Page#setColorScheme(ColorScheme.Value)}.
+ *
+ * @see Page#setColorScheme(ColorScheme.Value)
+ * @see Page#getColorScheme()
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@Inherited
+@Documented
+public @interface ColorScheme {
+
+    /**
+     * The initial color scheme for the application.
+     *
+     * @return the color scheme value
+     */
+    Value value() default Value.NORMAL;
+
+    /**
+     * Enumeration of supported color scheme values.
+     * <p>
+     * These values correspond to the CSS color-scheme property values and
+     * control how the browser renders UI elements and how the application
+     * responds to system color scheme preferences.
+     */
+    enum Value {
+        /**
+         * Light color scheme only. The application will use a light theme
+         * regardless of system preferences.
+         */
+        LIGHT("light"),
+
+        /**
+         * Dark color scheme only. The application will use a dark theme
+         * regardless of system preferences.
+         */
+        DARK("dark"),
+
+        /**
+         * Supports both light and dark color schemes, with a preference for
+         * light. The application can adapt to system preferences but defaults
+         * to light mode.
+         */
+        LIGHT_DARK("light dark"),
+
+        /**
+         * Supports both light and dark color schemes, with a preference for
+         * dark. The application can adapt to system preferences but defaults to
+         * dark mode.
+         */
+        DARK_LIGHT("dark light"),
+
+        /**
+         * Normal/default color scheme. Uses the browser's default behavior
+         * without any specific color scheme preference.
+         */
+        NORMAL("normal");
+
+        private final String value;
+
+        Value(String value) {
+            this.value = value;
+        }
+
+        /**
+         * Gets the CSS color-scheme property value.
+         *
+         * @return the CSS value string
+         */
+        public String getValue() {
+            return value;
+        }
+
+        /**
+         * Converts a string to a ColorScheme.Value enum.
+         *
+         * @param value
+         *            the CSS color-scheme value string
+         * @return the corresponding enum value, or NORMAL if not recognized
+         */
+        public static Value fromString(String value) {
+            if (value == null || value.isEmpty()) {
+                return NORMAL;
+            }
+            for (Value v : values()) {
+                if (v.value.equals(value)) {
+                    return v;
+                }
+            }
+            return NORMAL;
+        }
+    }
+}

flow-server/src/main/java/com/vaadin/flow/component/page/ExtendedClientDetails.java

@@ -60,6 +60,8 @@ public class ExtendedClientDetails implements Serializable {
     private double devicePixelRatio = -1.0D;
     private String windowName;
     private String navigatorPlatform;
+    private ColorScheme.Value colorScheme = ColorScheme.Value.NORMAL;
+    private String themeName;
 
     /**
      * For internal use only. Updates all properties in the class according to
@@ -100,14 +102,18 @@ public class ExtendedClientDetails implements Serializable {
      *            a unique browser window name which persists on reload
      * @param navigatorPlatform
      *            navigation platform received from the browser
+     * @param colorScheme
+     *            the current color scheme
+     * @param themeName
+     *            the theme name (e.g., "lumo", "aura")
      */
     public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
             String windowInnerWidth, String windowInnerHeight,
             String bodyClientWidth, String bodyClientHeight, String tzOffset,
             String rawTzOffset, String dstShift, String dstInEffect,
             String tzId, String curDate, String touchDevice,
             String devicePixelRatio, String windowName,
-            String navigatorPlatform) {
+            String navigatorPlatform, String colorScheme, String themeName) {
         this.ui = ui;
         if (screenWidth != null) {
             try {
@@ -184,6 +190,8 @@ public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
 
         this.windowName = windowName;
         this.navigatorPlatform = navigatorPlatform;
+        setColorScheme(ColorScheme.Value.fromString(colorScheme));
+        this.themeName = themeName;
     }
 
     /**
@@ -397,6 +405,36 @@ public boolean isIOS() {
                         && navigatorPlatform.startsWith("iPod"));
     }
 
+    /**
+     * Gets the color scheme.
+     *
+     * @return the color scheme, never {@code null}
+     */
+    public ColorScheme.Value getColorScheme() {
+        return colorScheme;
+    }
+
+    /**
+     * Gets the theme name.
+     *
+     * @return the theme name (e.g., "lumo", "aura"), or empty string if not
+     *         detected
+     */
+    public String getThemeName() {
+        return themeName;
+    }
+
+    /**
+     * Updates the color scheme. For internal use only.
+     *
+     * @param colorScheme
+     *            the new color scheme
+     */
+    void setColorScheme(ColorScheme.Value colorScheme) {
+        this.colorScheme = colorScheme == null ? ColorScheme.Value.NORMAL
+                : colorScheme;
+    }
+
     /**
      * Creates an ExtendedClientDetails instance from browser details JSON
      * object. This is intended for internal use when browser details are
@@ -446,7 +484,9 @@ public static ExtendedClientDetails fromJson(UI ui, JsonNode json) {
                 getStringElseNull.apply("v-td"),
                 getStringElseNull.apply("v-pr"),
                 getStringElseNull.apply("v-wn"),
-                getStringElseNull.apply("v-np"));
+                getStringElseNull.apply("v-np"),
+                getStringElseNull.apply("v-cs"),
+                getStringElseNull.apply("v-tn"));
     }
 
     /**

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java

@@ -83,6 +83,47 @@ public void setTitle(String title) {
         ui.getInternals().setTitle(title);
     }
 
+    /**
+     * Sets the color scheme for the page.
+     * <p>
+     * The color scheme is applied via a theme attribute on the html element,
+     * allowing CSS to use that attribute to target different color schemes. The
+     * theme attribute also ensures that browsers apply a color-scheme property
+     * accordingly.
+     *
+     * @param colorScheme
+     *            the color scheme to set (e.g., ColorScheme.Value.DARK,
+     *            ColorScheme.Value.LIGHT), or {@code null} to reset to NORMAL
+     */
+    public void setColorScheme(ColorScheme.Value colorScheme) {
+        if (colorScheme == null || colorScheme == ColorScheme.Value.NORMAL) {
+            executeJs("""
+                    document.documentElement.removeAttribute('theme');
+                    document.documentElement.style.colorScheme = '';
+                    """);
+            getExtendedClientDetails().setColorScheme(ColorScheme.Value.NORMAL);
+        } else {
+            executeJs("""
+                    document.documentElement.setAttribute('theme', $0);
+                    document.documentElement.style.colorScheme = '';
+                    """, colorScheme.getValue());
+            getExtendedClientDetails().setColorScheme(colorScheme);
+        }
+    }
+
+    /**
+     * Gets the color scheme for the page.
+     * <p>
+     * Note that this method returns the server-side cached value and will not
+     * detect color scheme changes made directly via JavaScript or browser
+     * developer tools.
+     *
+     * @return the color scheme value, never {@code null}
+     */
+    public ColorScheme.Value getColorScheme() {
+        return getExtendedClientDetails().getColorScheme();
+    }
+
     /**
      * Adds the given style sheet to the page and ensures that it is loaded
      * successfully.

flow-server/src/main/java/com/vaadin/flow/server/communication/IndexHtmlRequestHandler.java

@@ -177,7 +177,7 @@ public boolean synchronizedHandleRequest(VaadinSession session,
         }
 
         addDevBundleTheme(indexDocument, context);
-        applyThemeVariant(indexDocument, context);
+        applyColorScheme(indexDocument, context);
 
         if (config.isDevToolsEnabled()) {
             addDevTools(indexDocument, config, session, request);
@@ -253,8 +253,25 @@ private static void addDevBundleTheme(Document document,
         }
     }
 
-    private void applyThemeVariant(Document indexDocument,
+    private void applyColorScheme(Document indexDocument,
             VaadinContext context) {
+        // Check for @ColorScheme annotation first
+        AppShellRegistry registry = AppShellRegistry.getInstance(context);
+        Class<?> shell = registry.getShell();
+        if (shell != null) {
+            com.vaadin.flow.component.page.ColorScheme colorSchemeAnnotation = shell
+                    .getAnnotation(
+                            com.vaadin.flow.component.page.ColorScheme.class);
+            if (colorSchemeAnnotation != null) {
+                String colorScheme = colorSchemeAnnotation.value().getValue();
+                if (!colorScheme.isEmpty() && !colorScheme.equals("normal")) {
+                    indexDocument.head().parent().attr("theme", colorScheme);
+                }
+            }
+        }
+
+        // Also apply from deprecated @Theme variant attribute for backwards
+        // compatibility
         ThemeUtils.getThemeAnnotation(context).ifPresent(theme -> {
             String variant = theme.variant();
             if (!variant.isEmpty()) {

flow-server/src/main/java/com/vaadin/flow/server/startup/VaadinAppShellInitializer.java

@@ -35,6 +35,7 @@
 import com.vaadin.flow.component.dependency.StyleSheet;
 import com.vaadin.flow.component.page.AppShellConfigurator;
 import com.vaadin.flow.component.page.BodySize;
+import com.vaadin.flow.component.page.ColorScheme;
 import com.vaadin.flow.component.page.Inline;
 import com.vaadin.flow.component.page.Meta;
 import com.vaadin.flow.component.page.Push;
@@ -61,8 +62,9 @@
  */
 @HandlesTypes({ AppShellConfigurator.class, Meta.class, Meta.Container.class,
         PWA.class, Inline.class, Inline.Container.class, Viewport.class,
-        BodySize.class, PageTitle.class, Push.class, Theme.class, NoTheme.class,
-        StyleSheet.class, StyleSheet.Container.class })
+        BodySize.class, PageTitle.class, Push.class, ColorScheme.class,
+        Theme.class, NoTheme.class, StyleSheet.class,
+        StyleSheet.Container.class })
 // @WebListener is needed so that servlet containers know that they have to run
 // it
 @WebListener

flow-server/src/main/java/com/vaadin/flow/theme/Theme.java

@@ -100,9 +100,15 @@
 
     /**
      * The theme variant, if any.
+     * <p>
+     * <b>Deprecated:</b> Use {@link com.vaadin.flow.component.page.ColorScheme}
+     * annotation instead to set the color scheme for the application.
      *
      * @return the theme variant
+     * @deprecated Use {@link com.vaadin.flow.component.page.ColorScheme}
+     *             annotation instead
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     String variant() default "";
 
     /**

flow-server/src/test/java/com/vaadin/flow/component/page/ExtendedClientDetailsTest.java

@@ -51,6 +51,8 @@ public void initializeWithClientValues_gettersReturnExpectedValues() {
         Assert.assertEquals(2.0D, details.getDevicePixelRatio(), 0.0);
         Assert.assertEquals("ROOT-1234567-0.1234567", details.getWindowName());
         Assert.assertFalse(details.isIPad());
+        Assert.assertEquals(ColorScheme.Value.LIGHT, details.getColorScheme());
+        Assert.assertEquals("aura", details.getThemeName());
 
         // Don't test getCurrentDate() and time delta due to the dependency on
         // server-side time
@@ -161,14 +163,16 @@ private class ExtendBuilder {
         private String devicePixelRatio = "2.0";
         private String windowName = "ROOT-1234567-0.1234567";
         private String navigatorPlatform = "Linux i686";
+        private String colorScheme = "light";
+        private String themeName = "aura";
 
         public ExtendedClientDetails buildDetails() {
             return new ExtendedClientDetails(null, screenWidth, screenHeight,
                     windowInnerWidth, windowInnerHeight, bodyClientWidth,
                     bodyClientHeight, timezoneOffset, rawTimezoneOffset,
                     dstSavings, dstInEffect, timeZoneId, clientServerTimeDelta,
                     touchDevice, devicePixelRatio, windowName,
-                    navigatorPlatform);
+                    navigatorPlatform, colorScheme, themeName);
         }
 
         public ExtendBuilder setScreenWidth(String screenWidth) {