docs: improve upgrade guide theming section (#5052)

* docs: improve upgrade guide theming section

* address review comments

Author: sissbruecker

articles/upgrading/index.adoc

@@ -233,28 +233,17 @@ Below are the main highlights of the changes and more detailed instructions are
 
 The special `frontend/themes` folder, and the `components` sub-folder for CSS shadow-DOM injection, is deprecated (but still supported).
 
-Injecting CSS into Vaadin components’ shadow DOM through the components sub-folder in your `frontend/themes/<mytheme>` folder is disabled by default. Shadow DOM styling is no longer recommended (as of V24), but if you still need to use it, it can be enabled with the feature flag `themeComponentStyles`.
+Injecting CSS into Vaadin components’ shadow DOM through the `components` sub-folder in your `frontend/themes/<mytheme>` folder is disabled by default. Shadow DOM styling is no longer recommended (as of V24), but if you still need to use it, it can be enabled with the <<{articles}/flow/configuration/feature-flags#,`themeComponentStyles`>> feature flag.
 
-The [classname]`@Theme` annotation is deprecated. Instead, [classname]`StyleSheet` annotation to be used for loading one or more stylesheets from public static resources locations (e.g. `META-INF/resources/`), whereas [classname]`CssImport` loads one or more stylesheets from the `src/main/frontend/` folder and use mechanisms native to HTML, CSS, and React (e.g. `@import url("morestyles.css")` in CSS).
-
-`StyleSheet` annotation is now a recommended way to load Vaadin theme for the application — to be placed on the application class implementing [classname]`AppShellConfigurator`. Below are some examples of how to use it:
+The [annotationname]`@Theme` annotation is deprecated. Instead, the [annotationname]`@StyleSheet` annotation is now the recommended way to load Vaadin themes and custom application styles. The annotation should be placed on the application class implementing [classname]`AppShellConfigurator`:
 
 [source,java]
 ----
-// theme selection
+// Load Vaadin theme
 @StyleSheet(Aura.STYLESHEET) // or Lumo.STYLESHEET
+// Load application styles
+@StyleSheet("styles.css") // references src/main/resources/META-INF/resources/styles.css
 public class Application implements AppShellConfigurator {}
-
-// or loading custom styles and theme:
-
-@StyleSheet("styles.css")
-public class Application implements AppShellConfigurator {}
-
-// then using @import in the src/main/resources/META-INF/resources/styles.css:
-
-@import 'aura/aura.css'; /* or 'lumo/lumo.css' */
-// your custom styles go here ...
-
 ----
 
 Stylesheets referenced by [annotationname]`@StyleSheet` annotation are loaded by the servlet container. If the application is configured to use a custom URL mapping for the [classname]`VaadinServlet` (e.g. `vaadin.url-mapping` setting in Spring applications), the referenced stylesheet must be prefixed by the `context://` protocol.
@@ -315,16 +304,16 @@ The Lumo theme is no longer loaded by default, except if you’re using the [cla
 
 [source,java]
 ----
-@StyleSheet(Lumo.STYLESHEET);
+@StyleSheet(Lumo.STYLESHEET)
 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:
 
 [source,java]
 ----
-@StyleSheet(Lumo.STYLESHEET);
-@StyleSheet(Lumo.UTILITY_STYLESHEET);
+@StyleSheet(Lumo.STYLESHEET)
+@StyleSheet(Lumo.UTILITY_STYLESHEET)
 public class Application implements AppShellConfigurator {}
 ----