feat: add ColorScheme.Value.SYSTEM for intuitive system preference support (#22924)

Add SYSTEM enum constant to ColorScheme.Value that provides a more
intuitive name for developers wanting to follow system color scheme
preferences. This addresses the confusion around LIGHT_DARK and
DARK_LIGHT naming.

SYSTEM maps to the CSS value "light dark" (same as LIGHT_DARK),
supporting both light and dark modes while defaulting to light when
system preference cannot be determined.

Fixes #22891

Author: Artur-

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

@@ -33,7 +33,7 @@
  * Example usage:
  *
  * <pre>
- * &#64;ColorScheme(ColorScheme.Value.DARK)
+ * &#64;ColorScheme(ColorScheme.Value.SYSTEM)
  * public class AppShell implements AppShellConfigurator {
  * }
  * </pre>
@@ -98,7 +98,20 @@ enum Value {
          * system preferences, or other meta tags like
          * {@code <meta name="color-scheme" content="dark">}.
          */
-        NORMAL("normal");
+        NORMAL("normal"),
+
+        /**
+         * Use the system's preferred color scheme. Supports both light and dark
+         * modes, adapting to operating system or browser preferences. Defaults
+         * to light mode when system preference cannot be determined.
+         * <p>
+         * This provides a more intuitive name than LIGHT_DARK for the common
+         * use case of following system preferences. It is functionally
+         * equivalent to LIGHT_DARK, both mapping to the CSS value "light dark".
+         *
+         * @see #LIGHT_DARK
+         */
+        SYSTEM("light dark");
 
         private final String value;
 

flow-server/src/test/java/com/vaadin/flow/component/HasStyleTest.java

@@ -290,8 +290,9 @@ public void colorScheme_roundtripWorks() {
         HasStyleComponent component = new HasStyleComponent();
 
         for (ColorScheme.Value value : ColorScheme.Value.values()) {
-            if (value == ColorScheme.Value.NORMAL) {
-                continue; // NORMAL clears the property
+            if (value == ColorScheme.Value.NORMAL
+                    || value == ColorScheme.Value.SYSTEM) {
+                continue; // NORMAL clears the property, SYSTEM sets LIGHT_DARK
             }
             component.getStyle().setColorScheme(value);
             Assert.assertEquals("Roundtrip failed for " + value, value,

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

@@ -29,6 +29,7 @@ public void getValue_returnsCorrectValue() {
         Assert.assertEquals("dark light",
                 ColorScheme.Value.DARK_LIGHT.getValue());
         Assert.assertEquals("normal", ColorScheme.Value.NORMAL.getValue());
+        Assert.assertEquals("light dark", ColorScheme.Value.SYSTEM.getValue());
     }
 
     @Test
@@ -44,6 +45,8 @@ public void getThemeValue_multiValue_replacesSpaceWithHyphen() {
                 ColorScheme.Value.LIGHT_DARK.getThemeValue());
         Assert.assertEquals("dark-light",
                 ColorScheme.Value.DARK_LIGHT.getThemeValue());
+        Assert.assertEquals("light-dark",
+                ColorScheme.Value.SYSTEM.getThemeValue());
     }
 
     @Test
@@ -75,4 +78,15 @@ public void fromString_unrecognizedValue_returnsNormal() {
         Assert.assertEquals(ColorScheme.Value.NORMAL,
                 ColorScheme.Value.fromString("light-dark"));
     }
+
+    @Test
+    public void fromString_lightDark_returnsLightDarkNotSystem() {
+        // Ensure backward compatibility: parsing "light dark" returns
+        // LIGHT_DARK
+        Assert.assertEquals(ColorScheme.Value.LIGHT_DARK,
+                ColorScheme.Value.fromString("light dark"));
+        // SYSTEM and LIGHT_DARK should be functionally equivalent
+        Assert.assertEquals(ColorScheme.Value.LIGHT_DARK.getValue(),
+                ColorScheme.Value.SYSTEM.getValue());
+    }
 }