aura theme docs update

articles/styling/index.adoc

@@ -29,24 +29,24 @@ public class Application implements AppShellConfigurator {
 
 You can split your CSS over multiple stylesheets, and load them either with separate [annotationname]`@StyleSheet` annotations, or load additional stylesheets using the CSS `@import` rule.
 
-.src/main/resources/META-INF/resources/styles.css
+.`src/main/resources/META-INF/resources/styles.css`
 [source,css]
 ----
 @import "additional-styles.css";
 
 /* your CSS goes here */
 ----
 
-More details are provided in the <<{articles}/styling/stylesheets#, Stylesheets>> section.
+You can find more details in the <<{articles}/styling/stylesheets#, Stylesheets>> section.
 
-.Vaadin 24 way of applying styles is deprecated but supported
+.@Theme is deprecated but supported.
 [NOTE]
-The Vaadin 24 way of loading styles through the [annotationname]`@Theme` annotation and a theme folder in `frontend/themes` has been deprecated in Vaadin 25, but is still supported through the `themeComponentStyles` <<{articles}/flow/configuration/feature-flags#,feature flag>>. Please see the link:/docs/v24/styling[Vaadin 24 Styling documentation] for details on this usage.
+Loading styles through the [annotationname]`@Theme` annotation and a theme folder in `frontend/themes` has been deprecated, but is still supported through the `themeComponentStyles` <<{articles}/flow/configuration/feature-flags#,feature flag>>. See the link:/docs/v24/styling[Vaadin 24 Styling documentation] for details on this usage.
 
 
 == Themes
 
-By default, Vaadin components are rendered with their minimalistic built-in <<themes/base#, base styles>>, which are a good starting point if you want to customize the look and feel extensively. Vaadin also ships with two themes, <<themes/aura#, Aura>> and <<themes/lumo#, Lumo>>, that provide a more polished look and feel for Vaadin components.
+By default, Vaadin components are rendered with their simple built-in <<themes/base#, base styles>>, which are a good starting point if you want to customize the look and feel extensively. Vaadin also ships with two themes, <<themes/aura#, Aura>> and <<themes/lumo#, Lumo>>, that give a more polished look and feel for Vaadin components.
 
 [cols="^.^1, ^.^1, ^.^1"]
 |===
@@ -59,9 +59,9 @@ By default, Vaadin components are rendered with their minimalistic built-in <<th
 |image:_images/lumo-theme.png[Login form using the Lumo theme, width=100%]
 |===
 
-Vaadin themes can be loaded with the [annotationname]`@StyleSheet` annotation. The [classname]`Aura` and [classname]`Lumo` Java classes provide constants for the stylesheet path that can be used with the [annotationname]`@StyleSheet` annotation.
+Vaadin themes can be loaded with the [annotationname]`@StyleSheet` annotation. The [classname]`Aura` and [classname]`Lumo` Java classes have constants for the stylesheet path that can be used with the [annotationname]`@StyleSheet` annotation.
 
-Note that themes should be imported before any other styles in your application.
+Themes should be imported before any other styles in your application, so that style customizations have a higher specificity.
 
 [source,java]
 ----
@@ -73,7 +73,7 @@ public class Application implements AppShellConfigurator {
 }
 ----
 
-Both themes provide a comprehensive set of style properties (CSS custom properties) that make them easily customizable without complex CSS selectors. These properties are listed on the <<themes/aura#, Aura>> and <<themes/lumo#, Lumo>> reference pages.
+Both themes offer a comprehensive set of style properties (CSS custom properties) that make them customizable without complex CSS selectors. These properties are listed on the <<themes/aura#, Aura>> and <<themes/lumo#, Lumo>> reference pages.
 
 [source,css]
 ----
@@ -88,7 +88,7 @@ You can choose to apply your own styling on top of either theme, or on top of th
 
 == Component Style Properties
 
-Vaadin components also provide their own component-specific style properties for customizing their styles. These properties are listed on the Styling sub-pages in the component documentation (see e.g. <<{articles}/components/text-field/styling#,Text Field>>), along with the most common CSS selectors you can use to target the parts and states of components with your own CSS.
+Vaadin components also have their own component-specific style properties for customizing their styles. These properties are listed on the Styling sub-pages in the component documentation (e.g., <<{articles}/components/text-field/styling#,Text Field Styling>>), along with the most common CSS selectors you can use to target the parts and states of components with your own CSS.
 
 Component style properties differ from theme style properties in that they are specific to a particular component type.
 
@@ -103,7 +103,7 @@ html {
 
 == Applying CSS to Components
 
-The most common selectors needed to style Vaadin components are listed on the _Styling_ sub-pages in the component documentation (see e.g. <<{articles}/components/text-field/styling#,Text Field>>), along with the style properties built into the components.
+The most common selectors needed to style Vaadin components are listed on the _Styling_ sub-pages in the component documentation (e.g., <<{articles}/components/text-field/styling#,Text Field Styling>>), along with the style properties built into the components.
 
 .Applying custom CSS to a component's state and part
 [source,css]
@@ -116,20 +116,21 @@ vaadin-button[disabled]::part(label) {
 
 == Component Style Variants
 
-Many Vaadin components also have style variants as built-in features. These can be found in the documentation for each component.
+Many Vaadin components also have style variants as a built-in feature. You can find supported variants in the documentation for each component.
 
 .Button component variants in Aura theme
-image::_images/component-variants.png[width=50%]
+[.fill.white]
+image::_images/component-variants.png[width=612]
 
 
 == Recommended Approach
 
 The recommended approach to styling Vaadin components is:
 
 *  *Theme*: choose the <<{articles}/styling/themes#,theme>> that is the best match to your desired look and feel for components, or stick to the components’ base styles if neither theme is a good match;
-*  *Variant*: check if the component provides a style variant that corresponds (at least partially) to what you’re after;
+*  *Variant*: check if the component provides a style variant that corresponds (at least partially) to what you're after;
 *  *Style Properties*: customize the component using <<{articles}/styling/styling-components#theme-style-properties,theme>> and/or <<{articles}/styling/styling-components#component-style-properties,component style properties>>;
-*  *CSS style blocks*: <<{articles}/styling/styling-components#writing-css-for-vaadin-components,write your own CSS>> (using documented selectors) only once you can’t get further with the above approaches.
+*  *CSS style blocks*: <<{articles}/styling/styling-components#writing-css-for-vaadin-components,write your own CSS>> (using documented selectors) only once you can't get further with the above approaches.
 
 .Shadow DOM Styling Not Recommended
 [NOTE]
@@ -149,7 +150,7 @@ warningBox.addClassNames("bg-orange-400 p-20px");
 
 == Inline Styles
 
-Inline CSS can also be applied to individual elements and components through the [methodname]`getStyle()` Java API. These should be used sparingly to avoid hard-to-maintain spaghetti code, but can be useful e.g. for applying styles dynamically based on business logic.
+Inline CSS can also be applied to individual elements and components through the [methodname]`getStyle()` Java API. These should be used sparingly to avoid hard-to-maintain spaghetti code, but can be useful, for example, for applying styles dynamically based on business logic.
 
 [source,java]
 ----

articles/styling/stylesheets.adoc

@@ -13,7 +13,7 @@ In most project configurations, <<{articles}/styling/stylesheets#, stylesheets>>
 
 In both cases they are loaded with the [annotationname]`@StyleSheet` annotation.
 
-In most cases you should apply [annotationname]`@StyleSheet` annotations to the main application class that implements the [interfacename]`AppShellConfigurator` interface. This ensures that the CSS in it is applied globally, up-front, when the application UI is loaded into the browser.
+Usually, you should apply [annotationname]`@StyleSheet` annotations to the main application class that implements the [interfacename]`AppShellConfigurator` interface. This ensures that the CSS in it is applied globally, up-front, when the application UI is loaded into the browser.
 
 [source,java]
 ----
@@ -52,7 +52,7 @@ public class Application implements AppShellConfigurator {}
 
 == External Stylesheets
 
-All of the above methods for loading stylesheets also allow you to load stylesheets from external URIs, including other domains, by supplying an absolute path to [annotationname]`@StyleSheet` or `@import`.
+All methods mentioned before for loading stylesheets also allow you to load stylesheets from external URIs, including other domains, by supplying an absolute path to [annotationname]`@StyleSheet` or `@import`.
 
 [source,java]
 ----
@@ -63,7 +63,7 @@ public class Application implements AppShellConfigurator {
 }
 ----
 
-.src/main/resources/META-INF/resources/styles.css
+.`src/main/resources/META-INF/resources/styles.css`
 [source,css]
 ----
 @import "https://example.com/external-styles.css";
@@ -73,7 +73,7 @@ You can link:https://developer.mozilla.org/en-US/docs/Web/CSS/@import[read more
 
 == Lazy-Loading Stylesheets
 
-If you want to delay the loading of a particular stylesheet until it’s needed – for example if the stylesheet is big and only needed in a particular view or Flow component – you can apply the [annotationname]`@StyleSheet` annotation to its class instead of the main application class.
+If you want to delay the loading of a particular stylesheet until it's needed – for example if the stylesheet is big and only needed in a particular view or Flow component – you can apply the [annotationname]`@StyleSheet` annotation to its class instead of the main application class.
 
 [source,java]
 ----
@@ -83,7 +83,7 @@ public class CalendarView extends VerticalLayout {
 }
 ----
 
-Note that the stylesheet will remain loaded even after the user navigates away from the view, or when the component is no longer displayed, so you still need to ensure that the styles in it are scoped appropriately. You can use CSS class names to scope styles to a particular view or other part of the UI.
+The stylesheet remains loaded even after the user navigates away from the view, or when the component is no longer displayed. This means you still need to ensure that the styles in it are scoped appropriately. You can use CSS class names to scope styles to a particular view or other part of the UI.
 
 [source,java]
 ----
@@ -95,7 +95,7 @@ public class CalendarView extends VerticalLayout {
 }
 ----
 
-.src/main/resources/META-INF/resources/calendar-view.css
+.`src/main/resources/META-INF/resources/calendar-view.css`
 [source,css]
 ----
 .calendar-view {
@@ -108,15 +108,15 @@ public class CalendarView extends VerticalLayout {
 
 .CSS Class Names
 [NOTE]
-CSS class names are identifier-attributes applied to HTML elements in order to scope CSS styling to them. The same class name can be applied to multiple elements, and each element can have multiple class names. They have nothing to do with Java or TypeScript classes.
+CSS class names are identifier-attributes applied to HTML elements that scope CSS styling to them. The same class name can be applied to multiple elements, and each element can have multiple class names. They have nothing to do with Java or TypeScript classes.
 
 Stylesheets can also be <<{articles}/styling/advanced/dynamic-stylesheets#, loaded and unloaded dynamically>> through Java code.
 
 == Spring Security
 
 If you are using <<{articles}/flow/security/enabling-security#, Spring Security>> in your Vaadin application, you need to ensure that your stylesheets are accessible to unauthenticated users. The default Vaadin Spring Security configuration only permits access to `src/main/resources/META-INF/resources/styles.css` as well as the Aura and Lumo theme stylesheets.
 
-To allow access to additional stylesheets, you can modify your Spring Security configuration like so:
+To allow access to more stylesheets, you can modify your Spring Security configuration like so:
 
 [source,java]
 ----
@@ -143,7 +143,7 @@ public class SecurityConfig {
 
 This allows access to common locations for static resources, one of which is the `css` path. To make stylesheets available under that path, place them in the `src/main/resources/META-INF/resources/css` folder. For example, if you place a stylesheet in `src/main/resources/META-INF/resources/css/additional-styles.css`, you can import it in your main stylesheet like so:
 
-.src/main/resources/META-INF/resources/styles.css
+.`src/main/resources/META-INF/resources/styles.css`
 [source,css]
 ----
 @import "css/additional-styles.css";

articles/styling/themes/aura/app-layout.adoc

@@ -10,49 +10,46 @@ order: 30
 
 Aura offers customization options how the App Layout component renders the main content area.
 
-.Always use a unit when setting these property values to zero.
+.Always use a unit when setting these property values to zero
 [NOTE]
 These properties are used in CSS `calc()` functions and require a unit when setting the value to zero, e.g., `0px`.
 
 
 == Inset
 
+[.property-table]
 `--aura-app-layout-inset`::
 A length value that defines how much the navigation and content areas are inset within the browser viewport. You can set it to zero if you want to maximize the space that is available for the UI.
 +
 The inset is set to zero automatically once the browser viewport is below 800px width or 600px height.
 
-.Customizing the App Layout inset.
+.Customizing the App Layout inset
 [example]
 ====
-By default, the navigation and content is slightly inset from the edge of the browser viewport (indicated by the red outlines).
-
-[.device]
-image::_images/app-layout-inset.png[]
-
-When the inset is zero, the navigation and content areas take all the space within the browser viewport.
-
 [source,css]
 ----
 html {
   --aura-app-layout-inset: 0px;
 }
 ----
 
+.By default, the navigation and content is slightly inset from the edge of the browser viewport. When the inset is zero, the navigation and content areas take all the space within the browser viewport.
 [.device]
-image::_images/app-layout-inset2.png[]
+image::_images/app-layout-inset.png[]
+
 ====
 
 
 == Border
 
+[.property-table]
 `--aura-app-layout-border-radius`::
 Sets the border radius of the content area within the App Layout component. Effective only if `--aura-app-layout-inset` is not zero. Default is the <<../base#radius,base style L size border radius>>.
 
 `--aura-app-layout-border-width`::
 The border width around the App Layout content area.
 
-.Customizing the App Layout border radius.
+.Customizing the App Layout border radius
 [example]
 ====
 [source,css]