aura theme docs update

Author: jouni

articles/styling/_images/aura-theme-customized.png

@@ -294,7 +294,7 @@ A surface color that is tinted with the effective accent color.
 
 The surface level and opacity can only change on a predefined set of elements.
 
-While you might expect to be able to set the `--aura-surface-level` and `--aura-surface-opacity` property values at any level of the DOM hierarchy, that doesn't work. You can only change the level and opacity on elements that match the hard-coded list of selectors in Aura (https://github.com/vaadin/web-components/blob/4004d14275e2727147bcd085308f7f92481a9cf8/packages/aura/src/color.css#L49-L73[see full list]).
+While you might expect to be able to set the `--aura-surface-level` and `--aura-surface-opacity` property values at any level of the DOM hierarchy, that doesn't work. You can only change the level and opacity on elements that match the hard-coded list of selectors in Aura (https://github.com/vaadin/web-components/blob/391552e3b4e59f1aa7bc4f63aeef2a06d6ae0f9d/packages/aura/src/surface.css#L7-L41[see full list]).
 
 .Change the surface level of an element that matches the supported list of selectors.
 [example]

articles/styling/_images/aura-theme.png

@@ -1,25 +1,216 @@
 ---
 title: Aura
-page-title: Aura Theme Reference
-description: Aura Theme Reference
-meta-description: aura Theme Reference
+page-title: Aura theme documentation for Vaadin
+description: Learn how to use and customize the Aura theme to build modern, consistent Vaadin applications with minimal effort.
+meta-description: Learn how to use and customize the Aura theme to build modern, consistent Vaadin applications with minimal effort.
 order: 20
 ---
 
 
-= Aura Theme
+= Aura
 
-== Auto-Loading
+image::_images/aura-teaser.png[]
 
-When no [interfacename]`AppShellConfigurator` is defined in your application, the Aura theme CSS is automatically loaded as the default theme. In development mode, a log message suggests how to explicitly configure the theme.
+Aura is a theme for Vaadin applications that gives all official components a modern, cohesive look out of the box. Built as a collection of CSS styles and variants, it lets you get started quickly without designing or implementing a theme from scratch.
 
-To explicitly configure Aura, add the [annotationname]`@StyleSheet` annotation to your [interfacename]`AppShellConfigurator`:
+For many applications, Aura works as-is, with built-in variants covering common needs like sizing, emphasis, and component states (see <</components#,component documentation>> and the styling sub-pages for details on each component). When customization is needed, high-level CSS custom properties allow you to adjust the look and feel without dealing with complex CSS.
 
-[source,java]
+Aura is designed so you don't have to manage every detail manually. Colors, contrast, and surface hierarchy are computed automatically from a small set of base values, helping you stay consistent across different contexts. At the same time, you can go deeper and fine-tune individual properties when needed—moving fast by default, with full control available when required.
+
+
+== Aura Theme Editor
+
+[.theme-editor-teaser]
+video::/vaadin/videos/aura-theme-editor-teaser.webm[options="autoplay,loop"]
+
+++++
+<style>
+.theme-editor-teaser.videoblock .content {
+  height: auto;
+  padding-bottom: 0;
+  aspect-ratio: 1340 / 852;
+
+  video {
+    outline: 9px solid black;
+    outline-offset: -1px;
+    box-shadow: 0 10px 10px -3px black, 0 0 0 9px var(--docs-divider-color-1);
+  }
+}
+</style>
+++++
+
+The Aura theme editor allows you to visually explore the customization possibilities offered by the input properties. Use the *Shuffle* button to easily go through random combinations. If you see something you like, you can lock some options and continue exploring by shuffling the remaining unlocked options.
+
+Once you're satisfied with the end result, click the *Export CSS* button to get a CSS snippet that you can paste into your styles.css.
+(Note, that the “Use Navbar” options isn't something that's controlled by the theme – that's part of the app's layout/content).
+
+link:https://vaadin.github.io/web-components/aura.html[Try the Aura Theme Editor, role="button water primary"]
+
+
+== Custom Properties: Inputs vs Outputs
+
+Aura exposes many CSS custom properties (`--aura-*`). Some are meant to be overridden (inputs), while others are meant to be used as values (outputs).
+
+
+=== Properties You Can Override (“Inputs”)
+
+These are the properties you set to customize Aura. Aura uses them to compute consistent text, border, and surface colors (including light/dark handling).
+
+Examples include color-scheme-specific properties such as `--aura-background-color-light` / `--aura-background-color-dark` and `--aura-accent-color-light` / `--aura-accent-color-dark`, as well as sizing and typography inputs like `--aura-base-size` and `--aura-base-font-size`.
+
+You can still apply these properties as values in your own CSS, for example, the <<color#palette,palette colors>>.
+
+
+=== Read-Only “Output” Properties
+
+These are computed by Aura and are designed to be applied as values in your own CSS (for example, as `background`, `color`, or `border-color` values).
+
+They aren't technically read-only, but overriding them bypasses Aura's computation and makes it easier to accidentally break contrast or dark mode.
+
+The most common case is color-scheme-dependent properties:
+
+- Instead of overriding `--aura-background-color` (read-only), override `--aura-background-color-light` and `--aura-background-color-dark`.
+- Instead of overriding `--aura-accent-color` (read-only), override `--aura-accent-color-light` and `--aura-accent-color-dark`.
+
+When you override colors, test both color schemes (or restrict the app to one scheme) to avoid inconsistencies.
+
+See <<color#,Aura Color>> for the full color model, safe override points, and computed values.
+
+
+== Quick Reference
+
+=== Input Properties
+
+The following example overrides the most common and safest Aura customization inputs. Start with these before overriding lower-level properties or component-specific styles.
+
+[source,css]
 ----
-@StyleSheet(Aura.STYLESHEET)
-public class Application implements AppShellConfigurator {
+html {
+  /* Color */
+  color-scheme: dark;
+	--aura-content-color-scheme: light dark;
+	--aura-notification-color-scheme: dark;
+	--aura-background-color-light: #FFFFFF;
+	--aura-background-color-dark: #171717;
+  --aura-app-background: var(--aura-background-color);
+  --aura-accent-color-light: var(--aura-green);
+	--aura-accent-color-dark: var(--aura-green);
+	--aura-contrast-level: 2;
+  --aura-surface-level: -1;
+  --aura-red: #e7000b;
+  --aura-orange: #f54a00;
+  --aura-yellow: #efb100;
+  --aura-green: #009966;
+  --aura-blue: #155dfc;
+  --aura-purple: #9810fa;
+
+  /* Typography */
+  --aura-base-font-size: 15;
+  --aura-base-line-height: 1.5;
+  --aura-font-family: var(--aura-font-family-system);
+  --aura-font-weight-regular: 450;
+  --aura-font-weight-medium: 550;
+  --aura-font-weight-semibold: 650;
+
+  /* App Layout */
+  --aura-app-layout-inset: 0px;
+  --aura-app-layout-radius: 0px;
+  --aura-app-layout-border-width: 2px;
+
+  /* Other */
+  --aura-base-radius: 4;
+  --aura-base-size: 20;
 }
 ----
 
-Explicit configuration is recommended for production applications so the theme choice is clearly documented in code.
+
+// ++++
+// <style>
+// .collapsible-list details.small.small {
+//   > .title {
+//     font-size: var(--docs-font-size-s);
+//     padding-inline: var(--docs-space-m);
+//   }
+
+//   > .content {
+//     margin-inline: var(--docs-space-m);
+//     margin-bottom: var(--docs-space-s);
+//   }
+// }
+// </style>
+// ++++
+
+=== Output Properties
+
+Aura defines some properties as *read-only*. These are typically computed values that adapt to the effective color scheme and the inputs you override.
+
+You should generally not override these directly. Instead, override the corresponding input properties and use these properties as values in your own CSS.
+
+[source,css]
+----
+/* Color */
+--aura-neutral
+--aura-background-color
+--aura-accent-border-color
+--aura-accent-color
+--aura-accent-contrast-color
+--aura-accent-text-color
+--aura-surface-color
+--aura-surface-color-solid
+--aura-accent-surface
+--aura-red-text
+--aura-orange-text
+--aura-yellow-text
+--aura-green-text
+--aura-blue-text
+--aura-purple-text
+
+/* Typography */
+--aura-font-family-system
+--aura-font-family-instrument-sans
+--aura-font-size-xs
+--aura-font-size-s
+--aura-font-size-m
+--aura-font-size-l
+--aura-font-size-xl
+--aura-line-height-xs
+--aura-line-height-s
+--aura-line-height-m
+--aura-line-height-l
+--aura-line-height-xl
+
+/* Other */
+--aura-shadow-color
+--aura-shadow-xs
+--aura-shadow-s
+--aura-shadow-m
+--aura-overlay-shadow
+----
+
+
+.Use Read-Only Values (Don't Override Them)
+[example]
+====
+This example shows the intended pattern: use computed Aura values to style your own container, while keeping the theme consistent across light and dark schemes.
+[source,css]
+----
+.my-panel {
+	background: var(--aura-surface-color);
+	border: 1px solid var(--aura-accent-border-color);
+	border-radius: var(--vaadin-radius-l);
+	padding: var(--vaadin-padding-l);
+}
+
+.my-panel-title {
+	color: var(--aura-accent-text-color);
+	font-weight: var(--aura-font-weight-semibold);
+}
+----
+====
+
+
+== Reference
+
+For the full property reference and their corresponding safe override points, see the following sections.
+
+section_outline::[]

articles/styling/themes/aura/_images/aura-teaser.png

@@ -8,18 +8,42 @@ order: 40
 
 = Aura: Other Properties
 
+== Density & Sizing
+
 `--aura-base-size`::
-Aura redefines the base style <<../base#gap,gap>> and <<../base#padding,padding>> properties, and those values are computed based on this property. The property value is a number without a unit (i.e., _not_ a CSS length value). Suitable values range from 12 to 24. The resulting `--vaadin-gap` and `--vaadin-padding` values are defined with the `px` unit and are rounded to nearest 1px.
+Defines the density of the UI. Aura redefines the base style <<../base#gap,gap>> and <<../base#padding,padding>> properties, and those values are computed based on this property. The property value is a number without a unit (i.e., _not_ a CSS length value). Suitable values range from 12 to 24. The resulting `--vaadin-gap` and `--vaadin-padding` values are defined with the `px` unit and are rounded to nearest 1px. Prefer values divisible by 4 (i.e., 12, 16, 20, 24).
 
 `--aura-base-radius`::
 Aura redefines the base style <<../base#radius,radius>> properties, and those values are computed based on this property. The property is a number without a unit (i.e., _not_ a CSS length value). Suitable values range from 0 to 10, depending on the `--aura-base-size` value.
 +
 Setting the base radius to zero doesn't make all corners square. If you wish to remove all rounded corners, override the <<../base#radius,base style radius properties>> directly.
 
-`--aura-shadow-m`::
+
+== Shadows
+
 `--aura-shadow-color`::
+The color of shadows. Computed based on the `--aura-background-color` (color-scheme dependant).
+
+`--aura-shadow-xs`::
+Subtle shadow. Used for buttons and form inputs.
+
+`--aura-shadow-s`::
+Small shadow. Used for small overlays like tooltips, cards, and filled component variants like primary buttons and checked checkboxes.
+
+`--aura-shadow-m`::
+Prominent shadow. Used for most overlays like popovers, dialogs and notifications.
+
+
+== Overlays
 
 `--aura-overlay-shadow`::
+The default shadow for all overlays. Defaults to `--aura-shadow-m`.
+
 `--aura-overlay-outline-color`::
+The outer border color of overlays. Mostly visible with a light color scheme.
+
 `--aura-overlay-inner-outline-color`::
+The inner border color of overlays. Mostly visible with a dark color scheme.
+
 `--aura-overlay-backdrop-filter`::
+The backdrop filter for all overlays. By default, it lightens and blurs the content behind overlays. Only visible if <<color#surface-color,`--aura-overlay-surface-opacity`>> is less than 1.

articles/styling/themes/aura/color.adoc

@@ -1,25 +1,41 @@
 ---
-title: Themes and Base Styles
+title: Themes & Base Styles
 page-title: Vaadin themes and base styles
 description: An overview of Vaadin themes and base styles.
 meta-description: Discover Vaadin's themes and base styles to enhance your application's appearance.
 order: 60
 ---
 
 
-= Themes and Base Styles
+= Themes & Base Styles
 
-By default, Vaadin components are rendered with their minimal _base styles_. These can be a good starting point for creating a custom theme that should look significantly different than either of the two built-in themes.
+By default, Vaadin components are rendered with their minimal <<base#,_base styles_>>. These can be a good starting point for creating a custom theme that should look significantly different than either of the two built-in themes.
 
 .Login form using base styles
-image::../_images/base-styles.png[Login form using base styles, width=50%]
+image::../_images/base-styles.png[Login form using base styles, width=360]
+
+
+== Default Theme
+
+When no [interfacename]`AppShellConfigurator` is defined in your application, the Aura theme CSS is automatically loaded as the default theme. In development mode, a log message suggests how to explicitly configure the theme.
+
+To explicitly configure Aura, add the [annotationname]`@StyleSheet` annotation to your [interfacename]`AppShellConfigurator`:
+
+[source,java]
+----
+@StyleSheet(Aura.STYLESHEET)
+public class Application implements AppShellConfigurator {
+}
+----
+
+Explicit configuration is recommended for production applications so the theme choice is clearly documented in code.
 
 == Aura Theme
 
-Aura is one of the two built-in themes for Vaadin applications. It provides a modern, polished look and feel for all Vaadin components.
+<<aura#,Aura>> is the default theme for Vaadin applications, offering a modern and cohesive design for all official components. It works out of the box with built-in variants for common use cases, while also providing high-level CSS custom properties for easy customization. By computing colors, contrast, and surface hierarchy automatically, Aura lets you focus on your application while still achieving consistent, high-quality results.
 
 .Login form using the Aura theme
-image::../_images/aura-theme.png[[Login form using the Aura theme, width=50%]
+image::../_images/aura-theme.png[[Login form using the Aura theme, width=360]
 
 To load the Aura theme in your application, add it with a [annotationname]`@StyleSheet` annotation on your main application class. The [classname]`Aura` class provides a constant for the path to the Aura stylesheet that can be used with the [annotationname]`@StyleSheet` annotation.
 
@@ -32,33 +48,32 @@ public class Application implements AppShellConfigurator {
 }
 ----
 
-Note that themes should always be loaded _before_ any other styles in your application.
+Themes should always be loaded _before_ any other styles in your application.
 
-Aura includes a comprehensive set of style properties (custom CSS properties) that can be used to customize it without writing complicated CSS selectors. See the <<aura#,Aura style property reference>> for a complete list.
+Aura includes a comprehensive set of style properties (custom CSS properties) that can be used to customize it without writing complicated CSS selectors.
 
 .Login form using customized Aura theme
-image::../_images/aura-theme-customized.png[[Login form using customized Aura theme, width=50%]
+image::../_images/aura-theme-customized.png[[Login form using customized Aura theme, width=360]
 
 [source,css]
 ----
 html {
-  --aura-background-color-light: #e3ffe8;
-  --aura-font-family: Verdana;
-  --aura-base-font-size: 16;
-  --aura-base-radius: 10;
-}
-
-vaadin-button {
-  --aura-accent-color: #42C556;
+  --aura-accent-color-light: #009966;
+  --aura-background-color-light: #f3f1f1;
+  --aura-base-font-size: 15;
+  --aura-base-radius: 0;
+  --aura-base-size: 20;
+  --aura-contrast-level: 2;
+  --aura-font-family: var(--aura-font-family-system);
 }
 ----
 
 == Lumo Theme
 
-Lumo is the original Vaadin theme.
+<<lumo#,Lumo>> is a theme for Vaadin applications that offers a clean and consistent design for all official components. While Aura is the default theme, Lumo remains a dependable alternative with a strong focus on clarity, accessibility, and predictability. It provides a solid foundation for building applications or creating custom themes on top.
 
 .Login form using the Lumo theme
-image::../_images/lumo-theme.png[Login form using the Lumo theme, width=50%]
+image::../_images/lumo-theme.png[Login form using the Lumo theme, width=360]
 
 To load the Lumo theme in your application, add it with a [annotationname]`@StyleSheet` annotation on your main application class. The [classname]`Lumo` class provides a constant for the path to the Lumo stylesheet that can be used with the [annotationname]`@StyleSheet` annotation.
 
@@ -71,12 +86,12 @@ public class Application implements AppShellConfigurator {
 }
 ----
 
-Note that themes should always be loaded _before_ any other styles in your application.
+Themes should always be loaded _before_ any other styles in your application.
 
 Lumo includes a comprehensive set of style properties (custom CSS properties) that can be used to customize it without writing complicated CSS selectors. See the <<lumo/lumo-style-properties#,Lumo style property reference>> for a complete list.
 
 .Login form using customized Lumo theme
-image::../_images/lumo-theme-customized.png[Login form using customized Lumo theme, width=50%]
+image::../_images/lumo-theme-customized.png[Login form using customized Lumo theme, width=360]
 
 [source,css]
 ----