Clarify lumoImports silent deprecation in V25 upgrade guide

The lumoImports property in theme.json is silently ignored in
Vaadin 25, which can cause layouts using LumoUtility CSS classes
to appear broken without any error or warning. The CSS class names
are still added to the DOM but have no backing stylesheet.

Add an IMPORTANT callout near the theme.json deprecation note to
warn about this, and expand the Lumo Theme section to clarify that
@theme does not load utility classes and that applications
migrating from V24 with lumoImports in theme.json must add
@Stylesheet(Lumo.UTILITY_STYLESHEET).

Author: manolo

articles/upgrading/index.adoc

@@ -276,6 +276,11 @@ public class Application implements AppShellConfigurator {}
 
 The [filename]`theme.json` configuration file is deprecated (but still supported in the `frontend/themes/<mytheme>/` folder, except for the `lumoImports` property).
 
+[IMPORTANT]
+====
+The `lumoImports` property in [filename]`theme.json` is silently ignored in Vaadin 25. If your application relied on `lumoImports` to load utility classes (e.g., `"lumoImports": ["utility"]`), views using [classname]`LumoUtility` CSS classes for layout (flex, grid, gap, padding, etc.) will render with broken layouts. The class names are still added to the DOM but have no backing CSS rules. See <<lumo-theme>> for instructions on loading the Lumo Utility stylesheet.
+====
+
 The `themeFor` parameter of the [classname]`@CssImport` annotation (for shadow-DOM injection) is deprecated (but still supported).
 
 The special [filename]`document.css` file (for loading styles into the document root in embedded components) is removed as no longer necessary.
@@ -318,6 +323,7 @@ public SecurityFilterChain vaadinSecurityFilterChain(HttpSecurity http) throws E
 }
 ----
 
+[[lumo-theme]]
 === Lumo Theme
 
 The Lumo theme is no longer loaded by default, except if you’re using the [classname]`@Theme` annotation to load an application theme folder. If you’re not using [classname]`@Theme`, then add a [classname]`@StyleSheet` annotation to either your application class or a root layout to load the Lumo theme:
@@ -328,15 +334,19 @@ The Lumo theme is no longer loaded by default, except if you’re using the [cla
 public class Application implements AppShellConfigurator {}
 ----
 
-All Lumo styles, including badges, but excluding Lumo Utility Classes are included by default when the Lumo theme is loaded. To load the utility classes, add a separate [classname]`@StyleSheet` annotation:
+All Lumo styles, including badges, but excluding Lumo Utility Classes are included by default when the Lumo theme is loaded. This applies regardless of whether the theme is loaded through [classname]`@Theme` or [classname]`@StyleSheet`. To load the utility classes, add a [classname]`@StyleSheet` annotation:
 
 [source,java]
 ----
-@StyleSheet(Lumo.STYLESHEET)
 @StyleSheet(Lumo.UTILITY_STYLESHEET)
 public class Application implements AppShellConfigurator {}
 ----
 
+[NOTE]
+====
+If your Vaadin 24 application used `"lumoImports": ["utility"]` in [filename]`theme.json` to load the Lumo Utility Classes, you must add `@StyleSheet(Lumo.UTILITY_STYLESHEET)` when upgrading to Vaadin 25. The [classname]`@Theme` annotation does not load utility classes, and the `lumoImports` property in [filename]`theme.json` is no longer supported. Without this change, any layout built with [classname]`LumoUtility` constants (such as `Display.FLEX`, `FlexDirection.COLUMN`, `Gap.MEDIUM`, etc.) will appear broken, as the CSS class names are present in the HTML but have no associated styles.
+====
+
 The Lumo icon collection is not loaded by default anymore, except if you’re using the [classname]`@Theme` annotation to load an application theme folder. To ensure Lumo icons are included in your application bundle, use the [classname]`LumoIcon` enum instead of the general [classname]`Icon` class:
 
 [source,java,role="before"]