aura theme docs update

Author: jouni

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

@@ -65,3 +65,7 @@ html {
 [.device]
 image::_images/app-layout-radius.png[]
 ====
+
+
+
+include::index.adoc[tag=property-list-styles]

articles/styling/_images/aura-theme.png

@@ -187,7 +187,7 @@ Each palette color (excluding neutral, use the <<../base#text, base style text c
 
 .Aura Does Not Use Lumo CSS Variables
 [TIP]
-Aura has its own color system and does not use Lumo CSS custom properties like `--lumo-primary-color` or `--lumo-error-color`. To change the primary/accent color in Aura, use `--aura-accent-color-light` and `--aura-accent-color-dark` as described below. If you are migrating from Lumo, replace `--lumo-primary-color` with the Aura accent color properties.
+Aura has its own color system and does not use Lumo CSS style properties like `--lumo-primary-color` or `--lumo-error-color`. To change the primary/accent color in Aura, use `--aura-accent-color-light` and `--aura-accent-color-dark` as described below. If you are migrating from Lumo, replace `--lumo-primary-color` with the Aura accent color properties.
 
 `--aura-accent-color` **Read-only**::
 The accent color, used to highlight certain parts of the UI, like some interactive elements and selection states. Adapts to the color scheme. Don't override this property directly. Use the color-scheme-specific `--aura-accent-color-light` and `--aura-accent-color-dark` properties instead.
@@ -208,7 +208,8 @@ The accent contrast color for the light color scheme.
 The accent contrast color for the dark color scheme.
 
 `--aura-accent-text-color` **Read-only**::
-A text color derived from the accent color, providing more contrast against the background. Adapts to the color scheme. Don't override this property directly. Use the color-scheme-specific `--aura-accent-text-color-light` and `--aura-accent-text-color-dark` properties instead.
+A text color derived from the accent color, providing more contrast against the background. Adapts to the color scheme.
+// Use the color-scheme-specific `--aura-accent-text-color-light` and `--aura-accent-text-color-dark` properties instead.
 
 `--aura-accent-text-color-light` **Read-only**::
 The accent text color for the light color scheme.
@@ -294,7 +295,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]
@@ -364,3 +365,6 @@ Then, adjust the surface level and opacity on the component element, and reset i
 [.fill.white]
 image::_images/custom-surface-color.png[width=140]
 ====
+
+
+include::index.adoc[tag=property-list-styles]

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

@@ -1,25 +1,321 @@
 ---
 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 provides default styles and variants for all official components. It defines a consistent visual system out of the box, so you don’t need to build a theme from scratch.
 
-To explicitly configure Aura, add the [annotationname]`@StyleSheet` annotation to your [interfacename]`AppShellConfigurator`:
+Aura is designed to work at a high level by default. Colors, contrast, and surface hierarchy are derived from a small set of base values, so you don't have to manage every detail manually. At the same time, you can override individual style properties when you need more precise control.
+// (see the component styling pages, for example, <</components/button/styling#style-properties,Button Style Properties>>).
 
-[source,java]
+== Style Properties
+
+Together with <<../base#,base styles>>, Aura defines a set of style properties, prefixed with `--vaadin-` and `--aura-` for visual features like color, typography, sizing, whitespace. These style properties define the look and feel of Vaadin components. You can assign new values the these properties to customize the look and feel of Aura. You can also use these properties as CSS values in your stylesheets, to style your application's custom UI features.
+
+.Customizable vs Read-Only Properties
+[IMPORTANT.small]
+====
+Some style properties are designed to only be used in Vaadin components and custom UI compositions, not to be modified. Such properties are typically computed based on other, modifiable properties, for example, to support automatic light/dark color scheme switching. To customize these "read-only" properties, modify the corresponding non-read-only properties they are based on instead.
+
+As an example, the `--aura-background-color` property is read-only. Its value is computed from `--aura-background-color-light` or `--aura-background-color-dark`, depending on which light/dark mode of Aura is currently applied. Instead of modifying `--aura-background-color` directly, modify the two other properties, or only `--aura-background-color-light` if your application is not intended to support dark mode.
+
+Read-only properties are indicated on the Aura reference pages.
+====
+
+
+
+== Light and Dark Color Schemes
+
+Aura includes two color schemes: light and dark. By default only the light scheme is used, but you can your configure your application to use the dark scheme instead, or to switch dynamically between light and dark schemes based on user preferences. See the <<color#,Color>> reference page for more details on light and dark scheme usage.
+
+
+
+== Customizing Aura
+
+The look and feel that Aura applies to Vaadin components, and any custom UI compositions that you've styled with Aura properties, can be customized by assigning new values to Aura properties in a <</styling/stylesheets#,stylesheet>>.
+
+.Use Component Variants
+[TIP.small]
+Before customizing Aura or components directly, see if the built-in component variants are enough for your needs. They cover common cases like sizing, emphasis, and states, allowing most applications to work with minimal customization. See the component styling pages for reference, for example, <</components/button/styling#style-variants,Button Style Variants>> and <</components/grid/styling#style-variants,Grid Style Variants>>.
+
+[source,css]
+----
+html {
+  /* Color */
+	--aura-background-color-light: #FFFFFF;
+	--aura-background-color-dark: #171717;
+  --aura-accent-color-light: var(--aura-green);
+	--aura-accent-color-dark: var(--aura-green);
+	--aura-contrast-level: 2;
+  --aura-surface-level: -1;
+
+  /* Typography */
+  --aura-base-font-size: 15;
+  --aura-font-family: var(--aura-font-family-system);
+
+  /* Other */
+  --aura-base-radius: 4;
+  --aura-base-size: 20;
+}
+----
+
+The `html` root-level selector is used in the example above to apply the changes globally to the entire UI. Most Aura properties can also be customized separately for individual layouts or other elements by using other selectors. The <</styling/styling-elements#,Styling HTML Elements>> and <</styling/styling-components#,Styling Components>> pages provide more details on targeting different UI elements.
+
+All Aura properties are listed on the <<color#,Color>>, <<typography#,Typography>> and <<other#,Other Properties pages>>.
+
+
+=== 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"]
+
+
+// == 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]
+// ----
+// 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;
+// }
+// ----
+
+
+// ++++
+// <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]
 ----
-@StyleSheet(Aura.STYLESHEET)
-public class Application implements AppShellConfigurator {
+.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.
 
-Explicit configuration is recommended for production applications so the theme choice is clearly documented in code.
+section_outline::[]
+
+
+tag::property-list-styles[]
+++++
+<style>
+.dlist dl {
+  xbackground: var(--docs-surface-color-2);
+  border-radius: var(--docs-border-radius-l);
+  border: 1px solid var(--docs-divider-color-2);
+  gap: 0;
+  margin-block: 2em;
+
+  @media screen and (min-width: 40rem) {
+    dt, dd {
+      padding: 0.75em 0.9em;
+      align-self: stretch;
+
+      &:not(:first-of-type) {
+        border-top: 1px solid var(--docs-divider-color-1);
+      }
+    }
+
+    dt::before {
+      display: none;
+    }
+
+    dd {
+      border-left: 1px solid var(--docs-divider-color-1);
+    }
+  }
+
+  @media screen and (max-width: 40rem) {
+    padding: 1em;
+
+    dt {
+      margin-bottom: 0.5em;
+    }
+
+    dt::before {
+      width: calc(100% - 2em) !important;
+    }
+  }
+
+  dt code {
+    padding-inline-start: 0;
+    border: 0;
+    background: transparent;
+    font-weight: 600;
+    display: inline;
+  }
+
+  dt strong {
+    font-size: var(--docs-font-size-2xs);
+    border: 1px solid var(--docs-divider-color-2);
+    border-radius: var(--docs-border-radius-m);
+    padding-inline: 0.2em;
+    font-weight: 500;
+    color: var(--docs-secondary-text-color);
+    white-space: nowrap;
+  }
+}
+
+.exampleblock.exampleblock {
+  margin-block: 2em;
+}
+
+.exampleblock .content .code-example {
+  margin-inline: calc(var(--docs-space-m) * -1);
+  border-radius: 0;
+
+  &:first-child {
+    margin-top: calc(var(--docs-space-m) * -1);
+  }
+
+  &:last-child {
+    margin-bottom: calc(var(--docs-space-m) * -1);
+  }
+}
+</style>
+++++
+end::property-list-styles[]