Add Descriptions: security to styling (vaadin#2832)

Co-authored-by: Jouni Koivuviita <[email protected]>

articles/security/advanced-topics/architecture.adoc

@@ -4,6 +4,7 @@ description: An introduction to Vaadin Flow's security architecture and how it w
 order: 10
 ---
 
+
 = Security Architecture
 
 Vaadin Flow is a server-side framework, in which all your application state, business, and UI logic stay on the server. Unlike client-driven frameworks, a Flow application never exposes its internals to the browser, where vulnerabilities could be abused by an attacker.

articles/security/advanced-topics/external-configuration.adoc

@@ -1,9 +1,10 @@
 ---
 title: Storing Sensitive Data
-description: How to store sensitive data in a Vaadin application.
+description: Advice on storing sensitive data in Spring Boot applications.
 order: 250
 ---
 
+
 = Storing Sensitive Data in a Spring Boot Application
 
 It's often bad practice to put sensitive information, such as database URI, username, or password, in your [filename]`application.properties` file. If sensitive information is stored in project files or code, it might leak when you commit your project to source control management systems.

articles/security/advanced-topics/frequent-issues.asciidoc

@@ -1,9 +1,10 @@
 ---
 title: Frequently Reported Issues
-description: Lists issues reported by users as vulnerabilities, which in fact aren't.
+description: Lists perceived issues reported by users as vulnerabilities.
 order: 40
 ---
 
+
 = Frequently Reported Issues (False Positives)
 
 From time to time, Vaadin users perform security tests on the framework and report issues they find. Most of the time, the issues are false positives. The following is a list of commonly reported false positives and why they're false.

articles/security/advanced-topics/securing-plain-java-app.adoc

@@ -1,9 +1,10 @@
 ---
 title: Securing Plain Java Applications
-description: How to use the built-in security helpers in a plain Java application.
+description: Details and examples on using the built-in security helpers in a Java application.
 order: 50
 ---
 
+
 = Securing Plain Java Applications
 
 As described on the <<{articles}/security/enabling-security#, enabling security>> documentation page, Vaadin Flow comes with built-in security helpers that are most convenient to implement with Spring Boot and Spring Security. Although it's recommended to use Spring Security, it isn't always necessary.

articles/security/advanced-topics/security-practices.adoc

@@ -4,6 +4,7 @@ description: Provides an overview of the steps Vaadin takes to ensure an applica
 order: 20
 ---
 
+
 = Security Practices at Vaadin
 
 Vaadin takes several steps to ensure your application remains secure. They're described here.

articles/security/advanced-topics/vulnerabilities.asciidoc

@@ -4,6 +4,7 @@ description: Desriptions of common vulnerabilities (e.g., SQL injections, cross-
 order: 30
 ---
 
+
 = Common Vulnerabilities
 
 // tag::sql-injections[]

articles/security/enabling-security.adoc

@@ -1,6 +1,6 @@
 ---
 title: Enabling Security
-description: How to enable and configure security in a Vaadin Flow application using built-in security helpers with Spring Boot.
+description: Enabling and configuring security in an application using built-in security helpers with Spring Boot.
 order: 10
 ---
 
@@ -452,7 +452,6 @@ Vaadin strongly recommends not to mix Spring's URL-pattern-based HTTP security a
 
 [discussion-id]`4C8D835D-4E6E-4D81-BEA1-A865FEB17BAD`
 
-
 ++++
 <style>
 [class^=PageHeader-module--descriptionContainer] {display: none;}

articles/security/index.asciidoc

@@ -4,6 +4,7 @@ description: Documentation on better security with Vaadin products and related s
 order: 160
 ---
 
+
 [[security.overview]]
 = Security
 

articles/styling/advanced/custom-style-properties.adoc

@@ -4,6 +4,7 @@ description: How to create your own style properties.
 order: 20
 ---
 
+
 = Creating Style Properties
 
 CSS style properties are an effective way to define theme-wide styles that can be used to style both Vaadin components and other UI elements. Similar to variables and constants in Java, they allow you to reuse the same values in multiple places, instead of repeating the same literal value each time.

articles/styling/advanced/disabling-default-theme.adoc

@@ -1,9 +1,10 @@
 ---
 title: Disabling the Default Theme
-description: How to disable the default theme for an application.
+description: Explains how to disable the Lumo theme for an application.
 order: 110
 ---
 
+
 = Disabling the Default Theme
 
 Although not a recommended approach to styling Vaadin applications, the default Lumo theme can be disabled using the `@NoTheme` annotation. This is applied to the same class to which you would normally apply the <<../application-theme#applying-a-theme, `@Theme` annotation>>.

articles/styling/advanced/lazy-loading-stylesheets.adoc

@@ -1,9 +1,10 @@
 ---
 title: Lazy-Loading Stylesheets
-description: How to set certain stylesheets to be loaded only as needed.
+description: The basics of how to load large stylesheets only as needed.
 order: 60
 ---
 
+
 = Lazy-loading Stylesheets
 
 Stylesheets that are only needed when a particular view or other Flow-based UI class is loaded can be lazy loaded into the UI using a `@StyleSheet` annotation on the class.

articles/styling/advanced/loading-images-in-java.adoc

@@ -1,12 +1,13 @@
 ---
 title: Loading Theme Images from Java Code
-description: How to load theme images from Java code.
+description: Ensuring theme images are stored and loaded properly.
 order: 80
 ---
 
+
 = Loading Theme Images from Java Code
 
-Images and other assets in the theme folder -- except for stylesheets -- can be loaded from server side code, since the `frontend/themes` folder is automatically copied to the resource folder as part of the build process. The path to the theme folder is `themes/theme-name/`, where `theme-name` is the name of the theme folder.
+Images and other assets in the theme folder -- except for stylesheets -- can be loaded from server side code, since the `frontend/themes` folder is copied automatically to the resource folder as part of the build process. The path to the theme folder is `themes/theme-name/`, where `theme-name` is the name of the theme folder.
 
 [source]
 ----

articles/styling/advanced/loading-styles-dynamically.adoc

@@ -1,12 +1,13 @@
 ---
 title: Loading Stylesheets Dynamically
-description: How to load style sheets, dynamically.
+description: Explains how dynamically to load stylesheets.
 order: 70
 ---
 
+
 = Loading Stylesheets Dynamically
 
-Stylesheets can be loaded dynamically based on application logic on the server side. This can be useful for example to load styles based on the current user, or to allow the user to switch between different styles, manually.
+Stylesheets can be loaded dynamically based on application logic on the server side. This can be useful, for example, to load styles based on the current user, or to allow the user to switch between different styles, manually.
 
 This is done using the `addStyleSheet` method on the `Page` class, which takes a URL parameter. The URL can point either to a stylesheet served by the application itself, located in the resource folder `src/main/resources/META-INF/resources`, or to an external URL.
 

articles/styling/advanced/multi-app-themes.adoc

@@ -1,9 +1,10 @@
 ---
 title: Using a Theme in Multiple Applications
-description: How to use a theme in multiple applications.
+description: Steps and examples for using a theme in multiple applications.
 order: 30
 ---
 
+
 = Using a Theme in Multiple Applications
 
 An <<../application-theme#, application theme>> can be used in multiple applications by packaging it as a JAR dependency as shown in the following steps.

articles/styling/advanced/npm-packages.adoc

@@ -1,9 +1,10 @@
 ---
 title: Loading Theme Resources from npm Packages
-description: How to load theme resources from npm packages.
+description: Describes how to load theme resources from npm packages.
 order: 50
 ---
 
+
 = Loading Styles, Fonts & Images from npm Packages
 
 Stylesheets and other theme-related resources like font and image files can be loaded from npm packages through the theme configuration file `theme.json`.

articles/styling/advanced/parent-and-sub-themes.adoc

@@ -1,10 +1,11 @@
 ---
 title: Parent pass:[&] Sub-Themes
-description: How to set parent themes and sub-themes.
+description: Configuring parent themes, as well as sub-themes.
 order: 40
 ---
 
-= Parent Themes & Sub-Themes
+
+= Parent Themes pass:[&] Sub-Themes
 
 Multiple themes can be combined in the same application by configuring one of them as a _parent theme_ to the other. This is typically used for sharing a common base theme (<<multi-app-themes#, packaged as a JAR dependency>>) across multiple applications, and loading application-specific themes on top of the base theme.
 

articles/styling/advanced/runtime-theme-switching.adoc

@@ -1,9 +1,10 @@
 ---
 title: Run-time Theme Switching
-description: How to implement multiple sets of styles within a single theme and dynamically load them.
+description: Implementing multiple sets of styles within a single theme to be loaded dynamically.
 order: 80
 ---
 
+
 = Run-time Theme Switching Approaches
 
 Although the <<../application-theme#, application theme>> cannot strictly speaking be switched at run-time, it is possible to implement multiple distinct sets of styles (or _variants_) within a single theme, and to <<loading-styles-dynamically#, load styles, dynamically>>.

articles/styling/advanced/shadow-dom-styling.adoc

@@ -1,9 +1,10 @@
 ---
 title: Shadow DOM Styling of Components
-description: How to isolate JavaScript and CSS from the surrounding page.
+description: Details and instructions on isolating JavaScript and CSS from the surrounding page.
 order: 100
 ---
 
+
 = Shadow DOM Styling of Components
 
 Vaadin components use a native HTML feature called https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM[Shadow DOM, window=_blank] which isolates their JavaScript and CSS from the surrounding page. This helps simplify the internal scripting and styling of the components. It also means that traditional, global, or page-level CSS doesn't affect the elements inside the components. Instead, <<../styling-components/parts-and-states#shadow-parts, shadow parts>> and <<../lumo/lumo-style-properties#, style properties>> are used to expose many of these internal elements and styles for customization.

articles/styling/advanced/themes-for-embedded.adoc

@@ -1,9 +1,10 @@
 ---
 title: Application Themes for Embedded Components
-description: How to embed themes in an application's components.
+description: Things to consider when using a custom theme for embedded applications.
 order: 90
 ---
 
+
 = Application Themes for Embedded Components
 
 It's possible to <<{articles}/integrations/embedding#, embed>> an entire Vaadin application -- parts of one or custom Flow-based components -- into other web pages. The mechanism for doing so generates a custom Web Component that wraps the embedded UI inside its <<shadow-dom-styling#, Shadow DOM>>. This has certain implications for theming, which are covered in more detail in the <<{articles}/integrations/embedding/theming#, Theming Embedded Applications>> section.

articles/styling/application-theme.adoc

@@ -1,5 +1,6 @@
 ---
 title: Application Theme
+description: Advice on using a theme for styling an application.
 order: 20
 ---
 
@@ -218,3 +219,9 @@ Other theme configuration features are covered in the <<advanced#, Advanced Styl
 - <<advanced/parent-and-sub-themes#, Loading a parent theme as a basis for the current theme>>.
 
 [discussion-id]`e5e984e4-6a4f-40ab-a6fc-665166a2d8c5`
+
+++++
+<style>
+[class^=PageHeader-module--descriptionContainer] {display: none;}
+</style>
+++++

articles/styling/index.adoc

@@ -1,23 +1,20 @@
 ---
 title: Styling
+description: A brief overview of styling Vaadin applications.
 order: 55
 ---
 
 
 = Styling Overview
 
-This page contains a brief overview of the main aspects of styling Vaadin applications:
-
-- How to customize the styling of Vaadin components;
-- How to style other UI elements; and
-- Where to put your CSS code.
+This section contains a brief overview of the main aspects of styling Vaadin applications: how to customize the styling of Vaadin components; how to style other UI elements; and where to place your CSS code.
 
 The other pages in the Styling section provide further details on these methods and other related topics.
 
 
 == Customizing Component Styles
 
-The look and feel of Vaadin components is highly customizable in several ways:
+The look and feel of Vaadin components is highly customizable in several ways.
 
 
 === Built-in Style Variants
@@ -33,9 +30,7 @@ Button btn = new Button("Save");
 btn.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
 ----
 
-==== Further Reading
-
-<<../components#, Browse components>> to see their built-in style variants
+See <<../components#, Browse Components>> for information on built-in style variants.
 
 
 === Customizing Style Properties
@@ -62,7 +57,7 @@ vaadin-button {
 }
 ----
 
-.The effects of the above customizations.
+.Effects of Above Customizations
 [.fill.white]
 image::_images/lumo-properties-tweaked.png[The effects of the above customizations, 400]
 
@@ -88,11 +83,7 @@ vaadin-button.special {
 
 Style properties are recommended as the primary approach to both Vaadin component style customization and custom CSS. They make it easier to achieve a consistent look and feel across the application.
 
-
-==== More Information
-
-- <<lumo/lumo-style-properties#, List of Lumo style properties>>
-- <<styling-components#styling-components-with-style-properties, Styling components through style properties>>
+See <<lumo/lumo-style-properties#, List of Lumo style properties>> and <<styling-components#styling-components-with-style-properties, Styling components through style properties>> for more information on these properties.
 
 
 === Applying CSS to Components
@@ -119,7 +110,7 @@ vaadin-text-field[focused]::part(input-field) {
 }
 ----
 
-.Effects of the above CSS
+.Results of this CSS
 [.fill.white]
 image::_images/custom-styled-textfield.png[Effects of the above CSS]
 
@@ -138,11 +129,7 @@ vaadin-text-field.special::part(input-field) {
 }
 ----
 
-==== More Information
-
-- <<styling-components#styling-components-with-css, Styling components with CSS>>
-- <<../components#, Browse components to see their CSS selectors>>
-- <<styling-components/styling-component-instances#, Applying CSS to specific component instances# with CSS class names>>
+See <<styling-components#styling-components-with-css, Styling components with CSS>>, <<../components#, Browse components to see their CSS selectors>>, and <<styling-components/styling-component-instances#, Applying CSS to specific component instances# with CSS class names>> for more information.
 
 
 == Styling Other UI Elements
@@ -168,10 +155,7 @@ span.warning {
 }
 ----
 
-==== More Information
-
-- <<../create-ui/standard-html#, Native HTML element classes in Flow>>
-- <<styling-other-elements#, Applying CSS to native HTML elements>>
+See <<../create-ui/standard-html#, Native HTML element classes in Flow>> and <<styling-other-elements#, Applying CSS to native HTML elements>> for more information.
 
 
 === Applying Styles with Utility Classes
@@ -196,23 +180,19 @@ errorMsg.addClassNames(
 );
 ----
 
-.Effects of the above application of utility classes.
+.Effects Application of these Utility Classes
 [.fill.white]
 image::_images/utility-class-usage-example.png[Effects of the above application of utility classes, 300]
 
-.Lumo Utility Classes are for HTML elements, not for Vaadin components
 [NOTE]
 ====
 The Lumo utility classes are primarily designed to be used with native HTML elements, Vaadin layout components, and custom UI structures. Although some of them do work as expected on some Vaadin components, this is not their intended use. They can't be used to style the inner parts of components.
 ====
 
-
-==== More Information
-
-<<lumo/utility-classes#, Lumo Utility Classes>>
+See <<lumo/utility-classes#, Lumo Utility Classes>> for more information.
 
 
-== Locating and Loading Styles
+== Locating & Loading Styles
 
 Style property customizations and custom CSS are both placed in CSS stylesheets, typically in the application's theme folder. The theme folder is specified using the `@Theme` annotation.
 
@@ -241,10 +221,14 @@ Note that application projects generated with *Vaadin Start* have a theme folder
 [NOTE]
 `@CssImport` is supported, but not recommended. In older versions of Vaadin, stylesheets were loaded using `@CssImport` and `@Stylesheet` annotations, and in very old versions using the `@HtmlImport` annotation. While `@CssImport `and `@Stylesheet` still work, they are no longer recommended as the primary way to load styles into the UI.
 
-=== More Information
-
-<<application-theme#, Application theme folder>>
+See <<application-theme#, Application theme folder>> for more information.
 
 == Topics
 
 section_outline::[]
+
+++++
+<style>
+[class^=PageHeader-module--descriptionContainer] {display: none;}
+</style>
+++++

articles/styling/legacy/css-import.adoc

@@ -1,5 +1,6 @@
 ---
-title: CssImport annotation
+title: CssImport Annotation
+description: Information on the legacy CssImport annotation for importing stylesheets.
 ---
 
 
@@ -17,3 +18,9 @@ public class MyUI extends Div {
 ----
 
 Although this mechanism still works, the <<../application-theme#, application theme folder>> is now the recommended approach for loading stylesheets. It also supports <<../advanced/shadow-dom-styling#, injection of Shadow DOM styles>> into Vaadin components through the `components` sub-folder.
+
+++++
+<style>
+[class^=PageHeader-module--descriptionContainer] {display: none;}
+</style>
+++++