feat: add ColorScheme API with enum-based type-safe implementation

Replaced the ThemeVariant API with a new ColorScheme API that uses the
browser-native CSS color-scheme property instead of a custom theme attribute.
The API is fully type-safe using ColorScheme.Value enum.

Core Implementation:
- Created ColorScheme.Value enum: LIGHT, DARK, LIGHT_DARK, DARK_LIGHT, NORMAL
- Added @colorscheme annotation for setting initial color scheme on AppShell
- Page.setColorScheme(ColorScheme.Value) sets CSS color-scheme property
- Page.getColorScheme() returns ColorScheme.Value (never null, defaults to NORMAL)
- ExtendedClientDetails stores ColorScheme.Value internally
- String values from client automatically converted via ColorScheme.Value.fromString()

Frontend Changes:
- Flow.ts reads CSS color-scheme computed property
- Wire protocol parameter: v-cs (client to server)
- Theme name detection unchanged (v-tn for Lumo/Aura identification)

Backend Changes:
- Registered @colorscheme in VaadinAppShellInitializer
- IndexHtmlRequestHandler applies @colorscheme as inline style
- Deprecated @Theme.variant() with migration path to @colorscheme

Test Updates:
- All tests updated to use ColorScheme.Value enum
- Integration tests verify CSS color-scheme property (not attribute)
- Test CSS uses @media (prefers-color-scheme: dark) queries

Benefits:
- Type-safe API with compile-time checking
- Uses standard CSS property for browser integration
- Automatic form control and scrollbar adaptation
- No ambiguity about valid values
- Single, clean API surface

Backwards Compatibility:
- @theme(variant) still works via IndexHtmlRequestHandler for migration

Author: Artur-

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

@@ -539,15 +539,10 @@ export class Flow {
       params['v-np'] = ($wnd as any).navigator.platform;
     }
 
-    /* Theme variant from HTML element - supports both Lumo and Aura */
-    let themeAttr = document.documentElement.getAttribute('theme');
-    if (!themeAttr) {
-      // If no theme attribute, check for native color-scheme property
-      const colorScheme = getComputedStyle(document.documentElement).getPropertyValue('color-scheme').trim();
-      // "normal" is the default value and means no variant is set
-      themeAttr = colorScheme && colorScheme !== 'normal' ? colorScheme : '';
-    }
-    params['v-tv'] = themeAttr;
+    /* 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 = '';

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,7 +60,7 @@ public class ExtendedClientDetails implements Serializable {
     private double devicePixelRatio = -1.0D;
     private String windowName;
     private String navigatorPlatform;
-    private String themeVariant = "";
+    private ColorScheme.Value colorScheme = ColorScheme.Value.NORMAL;
     private String themeName;
 
     /**
@@ -102,8 +102,8 @@ public class ExtendedClientDetails implements Serializable {
      *            a unique browser window name which persists on reload
      * @param navigatorPlatform
      *            navigation platform received from the browser
-     * @param themeVariant
-     *            the current theme variant
+     * @param colorScheme
+     *            the current color scheme
      * @param themeName
      *            the theme name (e.g., "lumo", "aura")
      */
@@ -113,7 +113,7 @@ public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
             String rawTzOffset, String dstShift, String dstInEffect,
             String tzId, String curDate, String touchDevice,
             String devicePixelRatio, String windowName,
-            String navigatorPlatform, String themeVariant, String themeName) {
+            String navigatorPlatform, String colorScheme, String themeName) {
         this.ui = ui;
         if (screenWidth != null) {
             try {
@@ -190,7 +190,7 @@ public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
 
         this.windowName = windowName;
         this.navigatorPlatform = navigatorPlatform;
-        setThemeVariant(themeVariant);
+        setColorScheme(ColorScheme.Value.fromString(colorScheme));
         this.themeName = themeName;
     }
 
@@ -406,12 +406,12 @@ public boolean isIOS() {
     }
 
     /**
-     * Gets the theme variant.
+     * Gets the color scheme.
      *
-     * @return the theme variant, or empty string if not set
+     * @return the color scheme, never {@code null}
      */
-    public String getThemeVariant() {
-        return themeVariant;
+    public ColorScheme.Value getColorScheme() {
+        return colorScheme;
     }
 
     /**
@@ -425,13 +425,14 @@ public String getThemeName() {
     }
 
     /**
-     * Updates the theme variant. For internal use only.
+     * Updates the color scheme. For internal use only.
      *
-     * @param themeVariant
-     *            the new theme variant
+     * @param colorScheme
+     *            the new color scheme
      */
-    void setThemeVariant(String themeVariant) {
-        this.themeVariant = themeVariant == null ? "" : themeVariant;
+    void setColorScheme(ColorScheme.Value colorScheme) {
+        this.colorScheme = colorScheme == null ? ColorScheme.Value.NORMAL
+                : colorScheme;
     }
 
     /**
@@ -484,7 +485,7 @@ public static ExtendedClientDetails fromJson(UI ui, JsonNode json) {
                 getStringElseNull.apply("v-pr"),
                 getStringElseNull.apply("v-wn"),
                 getStringElseNull.apply("v-np"),
-                getStringElseNull.apply("v-tv"),
+                getStringElseNull.apply("v-cs"),
                 getStringElseNull.apply("v-tn"));
     }
 

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

@@ -84,35 +84,37 @@ public void setTitle(String title) {
     }
 
     /**
-     * Sets the theme variant for the page.
+     * Sets the color scheme for the page using the CSS color-scheme property.
+     * <p>
+     * The color scheme affects how the browser renders UI elements and allows
+     * the application to adapt to system color scheme preferences.
      *
-     * @param variant
-     *            the theme variant to set (e.g., "dark", "light"), or
-     *            {@code null} or empty string to remove the theme variant
+     * @param colorScheme
+     *            the color scheme to set (e.g., ColorScheme.Value.DARK,
+     *            ColorScheme.Value.LIGHT), or {@code null} to reset to NORMAL
      */
-    public void setThemeVariant(String variant) {
-        String newValue = (variant == null || variant.isEmpty()) ? null
-                : variant;
-        if (newValue == null) {
-            executeJs("document.documentElement.removeAttribute('theme');");
+    public void setColorScheme(ColorScheme.Value colorScheme) {
+        if (colorScheme == null || colorScheme == ColorScheme.Value.NORMAL) {
+            executeJs("document.documentElement.style.colorScheme = '';");
+            getExtendedClientDetails().setColorScheme(ColorScheme.Value.NORMAL);
         } else {
-            executeJs("document.documentElement.setAttribute('theme', $0);",
-                    newValue);
+            executeJs("document.documentElement.style.colorScheme = $0;",
+                    colorScheme.getValue());
+            getExtendedClientDetails().setColorScheme(colorScheme);
         }
-        getExtendedClientDetails().setThemeVariant(newValue);
     }
 
     /**
-     * Gets the theme variant for the page.
+     * Gets the color scheme for the page.
      * <p>
      * Note that this method returns the server-side cached value and will not
-     * detect theme changes made directly via JavaScript or browser developer
-     * tools.
+     * detect color scheme changes made directly via JavaScript or browser
+     * developer tools.
      *
-     * @return the theme variant, or empty string if not set
+     * @return the color scheme value, never {@code null}
      */
-    public String getThemeVariant() {
-        return getExtendedClientDetails().getThemeVariant();
+    public ColorScheme.Value getColorScheme() {
+        return getExtendedClientDetails().getColorScheme();
     }
 
     /**

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,12 +253,35 @@ 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("style",
+                            "color-scheme: " + colorScheme);
+                }
+            }
+        }
+
+        // Also apply from deprecated @Theme variant attribute for backwards
+        // compatibility
         ThemeUtils.getThemeAnnotation(context).ifPresent(theme -> {
             String variant = theme.variant();
             if (!variant.isEmpty()) {
-                indexDocument.head().parent().attr("theme", variant);
+                String existingStyle = indexDocument.head().parent()
+                        .attr("style");
+                String newStyle = existingStyle.isEmpty()
+                        ? "color-scheme: " + variant
+                        : existingStyle + "; color-scheme: " + variant;
+                indexDocument.head().parent().attr("style", newStyle);
             }
         });
     }

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 "";
 
     /**