diff --git a/articles/styling/_images/aura-theme-customized.png b/articles/styling/_images/aura-theme-customized.png index 4c699f26a9..ccfee7dad9 100644 Binary files a/articles/styling/_images/aura-theme-customized.png and b/articles/styling/_images/aura-theme-customized.png differ diff --git a/articles/styling/_images/aura-theme.png b/articles/styling/_images/aura-theme.png index f947ae71c9..3797c0f9cf 100644 Binary files a/articles/styling/_images/aura-theme.png and b/articles/styling/_images/aura-theme.png differ diff --git a/articles/styling/_images/component-variants.png b/articles/styling/_images/component-variants.png index 9960cfffaf..2dc08fef79 100644 Binary files a/articles/styling/_images/component-variants.png and b/articles/styling/_images/component-variants.png differ diff --git a/articles/styling/index.adoc b/articles/styling/index.adoc index 70def7ea6a..9e3389979c 100644 --- a/articles/styling/index.adoc +++ b/articles/styling/index.adoc @@ -29,7 +29,7 @@ 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"; @@ -37,16 +37,16 @@ You can split your CSS over multiple stylesheets, and load them either with sepa /* 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 <>, which are a good starting point if you want to customize the look and feel extensively. Vaadin also ships with two themes, <> and <>, that provide a more polished look and feel for Vaadin components. +By default, Vaadin components are rendered with their simple built-in <>, which are a good starting point if you want to customize the look and feel extensively. Vaadin also ships with two themes, <> and <>, 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 <> and <> 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 <> and <> 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,10 +116,11 @@ 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 @@ -127,9 +128,9 @@ image::_images/component-variants.png[width=50%] 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] ---- diff --git a/articles/styling/stylesheets.adoc b/articles/styling/stylesheets.adoc index b6549234b5..6bf7fbe8a3 100644 --- a/articles/styling/stylesheets.adoc +++ b/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,7 +108,7 @@ 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. @@ -116,7 +116,7 @@ Stylesheets can also be <<{articles}/styling/advanced/dynamic-stylesheets#, load 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"; diff --git a/articles/styling/themes/aura/_images/accent-colors.png b/articles/styling/themes/aura/_images/accent-colors.png index 2c2efcd0bc..d7bf45db57 100644 Binary files a/articles/styling/themes/aura/_images/accent-colors.png and b/articles/styling/themes/aura/_images/accent-colors.png differ diff --git a/articles/styling/themes/aura/_images/app-layout-inset.png b/articles/styling/themes/aura/_images/app-layout-inset.png index ef944de572..d3169a8ed1 100644 Binary files a/articles/styling/themes/aura/_images/app-layout-inset.png and b/articles/styling/themes/aura/_images/app-layout-inset.png differ diff --git a/articles/styling/themes/aura/_images/app-layout-inset2.png b/articles/styling/themes/aura/_images/app-layout-inset2.png deleted file mode 100644 index f34c14a768..0000000000 Binary files a/articles/styling/themes/aura/_images/app-layout-inset2.png and /dev/null differ diff --git a/articles/styling/themes/aura/_images/app-layout-radius.png b/articles/styling/themes/aura/_images/app-layout-radius.png index 28e60ac195..7a47b0e50c 100644 Binary files a/articles/styling/themes/aura/_images/app-layout-radius.png and b/articles/styling/themes/aura/_images/app-layout-radius.png differ diff --git a/articles/styling/themes/aura/_images/aura-teaser.png b/articles/styling/themes/aura/_images/aura-teaser.png new file mode 100644 index 0000000000..b05af1a399 Binary files /dev/null and b/articles/styling/themes/aura/_images/aura-teaser.png differ diff --git a/articles/styling/themes/aura/_images/background-colors.png b/articles/styling/themes/aura/_images/background-colors.png index 978f2aed94..7b51e2d5c1 100644 Binary files a/articles/styling/themes/aura/_images/background-colors.png and b/articles/styling/themes/aura/_images/background-colors.png differ diff --git a/articles/styling/themes/aura/_images/color-scheme-light-dark.png b/articles/styling/themes/aura/_images/color-scheme-light-dark.png index ffc06aa898..6804d8b8d4 100644 Binary files a/articles/styling/themes/aura/_images/color-scheme-light-dark.png and b/articles/styling/themes/aura/_images/color-scheme-light-dark.png differ diff --git a/articles/styling/themes/aura/_images/content-color-scheme.png b/articles/styling/themes/aura/_images/content-color-scheme.png index bc99c8f4ed..5d43f6baf4 100644 Binary files a/articles/styling/themes/aura/_images/content-color-scheme.png and b/articles/styling/themes/aura/_images/content-color-scheme.png differ diff --git a/articles/styling/themes/aura/_images/contrast-level.png b/articles/styling/themes/aura/_images/contrast-level.png index 699eea456e..46ce5173f7 100644 Binary files a/articles/styling/themes/aura/_images/contrast-level.png and b/articles/styling/themes/aura/_images/contrast-level.png differ diff --git a/articles/styling/themes/aura/_images/palette.png b/articles/styling/themes/aura/_images/palette.png new file mode 100644 index 0000000000..0fc551d851 Binary files /dev/null and b/articles/styling/themes/aura/_images/palette.png differ diff --git a/articles/styling/themes/aura/app-layout.adoc b/articles/styling/themes/aura/app-layout.adoc index b679680aa6..f67bfe28af 100644 --- a/articles/styling/themes/aura/app-layout.adoc +++ b/articles/styling/themes/aura/app-layout.adoc @@ -10,28 +10,22 @@ 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 { @@ -39,20 +33,23 @@ html { } ---- +.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] diff --git a/articles/styling/themes/aura/color.adoc b/articles/styling/themes/aura/color.adoc index dea2138d4d..680c75a86e 100644 --- a/articles/styling/themes/aura/color.adoc +++ b/articles/styling/themes/aura/color.adoc @@ -7,28 +7,23 @@ order: 10 --- = Aura Color -:toclevels: 2 -Aura defines its own color system, which it then maps to the base style color properties. Unless you need absolute control of the exact color values defined for text, borders, or backgrounds, you only need to override a few Aura color properties to get a customized color palette. +Aura defines a set of color properties that define the look and feel of Vaadin components and allow for easy customization of the theme. They can also be applied to custom UI compositions instead of native CSS values. -.Safari 17 Support -[CAUTION.small] -If you need to support Safari 17, avoid using the `light-dark()` function when overriding color properties, as the CSS relative color syntax – which Aura and base styles use – doesn't work together with the `light-dark()` function in Safari 17. This is why Aura defines color-scheme-specific light and dark properties. +As Aura is applied on top of Vaadin base styles, all base style properties (prefixed with `--vaadin-`) can also be used together with Aura. -.Read-Only Properties -[NOTE.small] -Properties which are marked “read-only” aren't technically read-only. While you can override their values, the intention is to use them only to set values of other properties. +== Light & Dark Color Schemes -== Color Scheme +Aura includes two color schemes: light and dark. By default only the light scheme is used. You can configure your application to use the dark scheme or to switch dynamically between light and dark schemes based on user preference. -You can choose between a light or a dark color scheme (i.e., light or dark mode), or configure the app to follow the user's operating system preference. The light color scheme is used by default. +The `color-scheme` CSS property is used to configure the application to use the light or dark scheme, or to switch automatically based on the operating system's settings as follows: -The color properties you can customize in Aura have both a light and dark variant, suffixed with `-light` and `-dark`. If you support both color schemes, remember to redefine both color properties if those are available. +- `color-scheme: light;` – only the light scheme is used (default). +- `color-scheme: dark;` – only the dark scheme is used. +- `color-scheme: light dark;` – the operating system's settings decide the scheme. -Use the native `color-scheme` property to control the app's global color scheme. See <> for more information about the related Java API. - -.Allowing the application color scheme to follow the operating system's color scheme. +.The global color scheme is either light or dark, depending on the operating system preference. [example] ==== [source,css] @@ -39,18 +34,25 @@ html { } ---- -.The global color scheme is either light or dark, depending on the operating system preference. [.device] image::_images/color-scheme-light-dark.png[] ==== -In addition to the global color scheme, you can configure the Notification and App Layout content area color schemes separately. This allows, for example, to always use the dark color scheme for the main navigation area while allowing the content/view area to follow the user's preference. +You can also apply this setting <> through the `@ColorScheme` annotation and the `Page::setColorScheme()` API. + +Correct use of Aura color properties ensures that appropriate colors are used for the active color scheme, but any other color values you use should be tested manually in both schemes. + + +=== Scoped Color Scheme + +Typically the same color scheme is applied globally to the entire UI, but Aura also allows you to apply a different color scheme to notifications and to the App Layout's content area, where most of your UI is rendered. This allows, for example, to always use the dark color scheme for the main navigation area while allowing the content/view area to follow the operating system's setting. +[.property-table] `--aura-content-color-scheme`:: -Defines the color scheme of the content area of the App Layout component, and is only effective when the App Layout component is used. Follows the global color scheme by default. +Applies a separate color scheme to the content area of App Layout. The App Layout drawer and navbar use the global color-scheme property. Has no effect if App Layout is not used. `--aura-notification-color-scheme`:: -Defines the color scheme of all notifications. Follows the global color scheme by default. +Applies a separate color scheme to all Notifications. .Use a different color scheme for the navigation and main content areas. @@ -70,57 +72,155 @@ html { image::_images/content-color-scheme.png[] ==== +.Changing the color scheme on all components and elements in the application isn't supported. +[CAUTION] +Applying the `color-scheme` property is only supported on a limited set of components and elements. You can view the link:https://github.com/vaadin/web-components/blob/c8681c44ee581fe51958ca1ae306e8f0d55c6353/packages/aura/src/color.css#L57-L93[list of supported CSS selectors]. + + + +=== Ensuring Compatibility with Both Light & Dark Schemes + +To ensure that any custom styling you apply to the UI works in the applied color scheme: + +- Use the `-light` and `-dark` suffixed properties, like `--aura-background-color-light` and `-aura-background-color-dark` to _customize_ that color. +- Use Aura color properties without the `-light` or `-dark` suffix, such as `--aura-background-color`, when _applying_ color values to UI elements. + +[source,css] +---- +/* Use light/dark-suffixed properties for customization */ +html { + --aura-accent-color-light: #ffd06b; + --aura-accent-color-dark: #1b0f38; +} + +/* Use un-suffixed properties as values */ +.some-ui-element { + background-color: var(--aura-accent-color); +} +---- + +Any other color values you use won't automatically adapt to the color scheme, unless you provide separate values for each using the `light-dark()` CSS function: + +[source,css] +---- +.some-ui-element { + background-color: light-dark(white, black); +} +---- + +[[light-dark-function]] +.Avoid light-dark() in Aura Customization +[CAUTION] +==== +In Safari 17, the `light-dark()` function does not work with the way many Aura color properties are implemented. This limitation is most notable with the <<#saturated-palette,saturated palette colors>>, which need to use the same color in both light and dark color schemes if you want to support Safari 17. + +You can use the `light-dark()` function to assign values to properties marked with [.badge.light-dark]#light-dark()# or xref:./#read-only-properties[Read-only,role=badge]. +==== + == Background Color -`--aura-background-color` **Read-only**:: -The base background color. Adapts to the color scheme. Don't override this property directly. Use the color-scheme-specific `--aura-background-color-light` and `--aura-background-color-dark` properties instead. +[.property-table] +`--aura-app-background` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +The main background image, used for the `` element and the App Layout content area. By default this is a computed gradient, based on the `--aura-background-color` property, which becomes more prominent with more saturated background colors. You can also set it to a solid color as well. + +`--aura-background-color` xref:./#read-only-properties[Read-only,role=badge]:: +The primary background color that defines the overall tone of the application. This color is used to computed <<#text-color,text>>, <<#border-color,border>>, and <<#surface-color,surface>> colors. Automatically assigned the value of the `-light` or `-dark` suffixed property, depending on the active color scheme. `--aura-background-color-light`:: -The base background color for the light color scheme. +The primary background color of the application for the light color scheme. `--aura-background-color-dark`:: -The base background color for the dark color scheme. +The primary background color of the application for the dark color scheme. + +`--vaadin-background-container` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +Background for “containers”, buttons, toolbars, notifications, and other highlighted content areas. By default computed from --aura-background-color and --aura-contrast-level. Use this color if you want a darker background in the light color scheme and a lighter color in the dark color scheme. -`--aura-app-background`:: -The main app background, used for the `` element and the App Layout content area. By default this is a computed gradient, based on the `--aura-background-color` property, which becomes more prominent with more saturated background colors. You can set it to a solid color if you want to, for example, to `var(--aura-background-color)`. +`--vaadin-background-container-strong` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +A more prominent variant of the `--vaadin-background-container` color. -You can also use the <<../base#background,base style background color properties>>. -.Using custom and highly saturated background colors, making the gradient background more prominent. +.Using custom and highly saturated background colors, making the gradient background more prominent [example] ==== +In this following example, a dark blue color is used for the dark color scheme in the global/navigation areas and a bright yellow for the light color scheme in the content area. [source,css] ---- html { - --aura-background-color-light: #ffd06b; - --aura-background-color-dark: #1b0f38; + --aura-background-color-light: khaki; + --aura-background-color-dark: darkslateblue; + + /* Set the main color scheme to dark */ + color-scheme: dark; + + /* Set the color scheme of the AppLayout content area to light */ + --aura-content-color-scheme: light; } ---- -.Using a dark purple for the dark color scheme (global/navigation areas) and a bright yellow for the light color scheme (content area). [.device] image::_images/background-colors.png[] ==== -[[text-and-border-colors]] -== Text & Border Colors +[[text-color]] +== Text Color -Aura redefines the base style <<../base#text-color,text color>> and <<../base#border-color,border color>> properties. These colors are computed based on the background color properties, and automatically adapt to the color scheme. +Aura uses the `--vaadin`-prefixed <<../base#text-color,base style text properties>> by assigning its own computed, color-scheme-adapted values to them. Aura also defines a text color that is tinted with the <> as well as text colors for each of the <<#palette,palette colors>>. -In addition to base style border colors, Aura defines a border that is tinted with the <>. +[.property-table] +`--vaadin-text-color` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +The main text color used in the UI. Defaults to the <<#neutral,neutral color>>. -`--aura-accent-border-color` **Read-only**:: -A border color that is slightly tinted with the `--aura-accent-color` and that you can pair together with the `--aura-accent-surface` color. +`--vaadin-text-color-secondary` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +A secondary text color, with at least 4.5:1 contrast ratio with the main background color. Computed from `--vaadin-text-color` by default. +`--vaadin-text-color-disabled` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +Text color for disabled text. Computed from `--vaadin-text-color` by default. -=== Text & Border Color Contrast +`--aura-accent-text-color` xref:./#read-only-properties[Read-only,role=badge]:: +A text color derived from the accent color, with at least 4.5:1 contrast ratio with the main background color. -`--aura-contrast-level`:: -Increase or decrease the contrast of the computed text border colors with this property. +`--aura-accent-text-color` xref:./#read-only-properties[Read-only,role=badge]:: +A text color derived from the accent color, with at least 4.5:1 contrast ratio with `--aura-background-color`. + +`--aura-accent-text-color-light`:: +The accent text color for the light color scheme. Computed from `--aura-accent-color-light` by default. If you use a custom color, make sure it has at least 4.5:1 contrast with the background color. + +`--aura-accent-text-color-dark`:: +The accent text color for the dark color scheme. Computed from `--aura-accent-color-dark` by default. If you use a custom color, make sure it has at least 4.5:1 contrast with the background color. + +`--aura-*-text`:: +See <<#saturated-palette,saturated palette colors>>. + + + +[[border-color]] +== Border Color + +Aura uses the `--vaadin`-prefixed <<../base#border-color,base border properties>> by assigning its own computed, color-scheme-adapted values to them, but also provides its own <<#accent-color,accent>> border color. + +Border colors are by default computed based on other color properties and the <<#contrast,contrast>> level. The most common way to customize border colors is to adjust the contrast level. + +[.property-table] +`--aura-accent-border-color` xref:./#read-only-properties[Read-only,role=badge]:: +A border color that is slightly tinted with the <<#accent-color>,accent color>, designed to be paired together with the `--aura-accent-surface` color. + +`--vaadin-border-color` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +A high-contrast border color. By default computed from `--aura-background-color` and `--aura-contrast-level` in Aura. + +`--vaadin-border-color-secondary` xref:#light-dark-function[light-dark(),role="badge light-dark"]:: +A low-contrast border color. By default computed from `--aura-background-color` and `--aura-contrast-level` in Aura. -If you explicitly override any text or border color properties the `--aura-contrast-level` property no longer affects them, unless you use it in your own computed colors. + + +== Contrast + +All text and border colors in Aura are by default computed based on the customizable `--aura-contrast-level` property. This is an efficient way to adjust the overall color contrast in your UI. + +[.property-table] +`--aura-contrast-level`:: +Increase or decrease the contrast of the computed text and border colors with this property. Reasonable values range between `0` and `5`. The default value is `1`. .Increase the contrast level to make text and border colors stronger. [example] @@ -128,69 +228,93 @@ If you explicitly override any text or border color properties the `--aura-contr [source,css] ---- html { - --aura-contrast-level: 10; + --aura-contrast-level: 5; } ---- -[.device] -image::_images/contrast-level.png[] +.The screenshot on the left uses contrast level 0, while the screenshot on the right uses contrast level 5. +image::_images/contrast-level.png[Two screenshots side by size, one showing a low contrast and the other high contrast text and border colors] ==== +.Use caution when using low contrast levels. +[CAUTION] +The default Aura colors are evaluated to meet WCAG 2.1 color contrast requirements. Make sure to evaluate the color contrast manually when using a contrast level lower than the default. -== Palette +If you explicitly override any text or border color properties the `--aura-contrast-level` property no longer affects them, unless you use it in your own computed colors. -Aura offers a palette of seven colors: **neutral**, **red**, **orange**, **yellow**, **green**, **blue**, and **purple**. The palette doesn't offer traditional color scales that many design systems include, where you have 10 to 12 colors per hue ranging from almost white to almost black, commonly named from 50/100 to 900. -The palette consists of single color values, from which all necessary variations of that color are computed automatically (the text, border and surface/background variants). If you need more than what Aura and the <<../base#,base styles>> offer out of the box, you can use the native CSS https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/color-mix[`color-mix()`] and https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Colors/Using_relative_colors[relative color functions]. +== Palette -.Example: Create a semi-transparent version of the `--aura-red` color -[source,css] ----- -html { - --aura-red-200: color-mix(in srgb, var(--aura-red) 20%, transparent); -} ----- +Aura offers a palette of seven colors: **neutral**, **red**, **orange**, **yellow**, **green**, **blue**, and **purple**. +[[neutral-color]] === Neutral Color (Grayscale) -The neutral color forms the basis of your theme, as it's used for text and border colors by default. The `--aura-neutral` color adapts to the color scheme, using either the light or dark version of the property, where the light version is a dark gray and the dark version is off-white color by default. +The neutral color, which is computed from the `--aura-background-color-light` and `--aura-background-color-dark` properties by default, is used for the <<#text-color,text>> and <<#border-color,border>> colors. + +[.property-table] +`--aura-neutral` xref:./#read-only-properties[Read-only,role=badge]:: +Automatically assigned the value of the `-light` or `-dark` suffixed property, depending on the active color scheme. + +`--aura-neutral-light`:: +A dark gray by default. -`--aura-neutral`, `--aura-neutral-light`, `--aura-neutral-dark`. +`--aura-neutral-dark`:: +White by default. +[[saturated-palette]] === Saturated Colors -These saturated palette colors are meant to be used as accent colors. You can override the palette with custom colors, for example, from your brand guidelines. +image::_images/palette.png[] + +These saturated palette colors are meant to be used as <<#accent-color,accent>> colors, for example, with the <> component together with the <<#accent-color-class-names>>. You can override the palette with custom colors, for example, from your brand guidelines. + +Each color has a corresponding text color property that provides appropriate <<#contrast,contrast>> against the background. + +[%header] +|=== +|Generic Color | Text Color +|`--aura-red` | `--aura-red-text` xref:./#read-only-properties[Read-only,role=badge] +|`--aura-orange` | `--aura-orange-text` xref:./#read-only-properties[Read-only,role=badge] +|`--aura-yellow` | `--aura-yellow-text` xref:./#read-only-properties[Read-only,role=badge] +|`--aura-green` | `--aura-green-text` xref:./#read-only-properties[Read-only,role=badge] +|`--aura-blue` | `--aura-blue-text` xref:./#read-only-properties[Read-only,role=badge] +|`--aura-purple` | `--aura-purple-text` xref:./#read-only-properties[Read-only,role=badge] +|=== -`--aura-red`, -`--aura-orange`, -`--aura-yellow`, -`--aura-green`, -`--aura-blue`, -`--aura-purple`. -=== Text Colors +=== Computing a Traditional Color Scale -Each palette color (excluding neutral, use the <<../base#text, base style text colors>>) has a corresponding text color property which has more contrast against the background color, making it suitable to be used for colored text. +Aura doesn't offer traditional color scales that many design systems include, where you have 10 to 12 colors per hue ranging from almost white to almost black, commonly named from 50/100 to 900, or as `10pct` to `90pct` in the Lumo theme. -`--aura-red-text`, -`--aura-orange-text`, -`--aura-yellow-text`, -`--aura-green-text`, -`--aura-blue-text`, -`--aura-purple-text`. +The Aura palette consists of single saturated color values, from which all necessary variations of that color are computed automatically (the text, border, and surface/background variants). If you need more than what Aura and the <<../base#,base styles>> offer out of the box, you can use the native CSS https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/color-mix[`color-mix()`] and https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Colors/Using_relative_colors[relative color functions] to compute more color properties. + +.Example: Computing color variants based on the `--aura-red` property +[example] +==== +[source,css] +---- +html { + /* A variant of --aura-red mixed with 20% --aura-background-color */ + --aura-red-light: color-mix(in srgb, var(--aura-red) 80%, var(--aura-background-color); + + /* A variant of --aura-red with 20% opacity */ + --aura-red-20pct: rgb(var(--aura-red) / 20%); +} +---- +==== == Accent Color -.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. +The accent color is used to highlight certain UI parts and states, such as buttons, selections, and keyboard focus (similarly to the primary color in the Lumo theme). -`--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. +[.property-table] +`--aura-accent-color` xref:./#read-only-properties[Read-only,role=badge]:: +Automatically assigned the value of the `-light` or `-dark` suffixed property, depending on the active color scheme. `--aura-accent-color-light`:: The accent color for the light color scheme. @@ -198,44 +322,29 @@ The accent color for the light color scheme. `--aura-accent-color-dark`:: The accent color for the dark color scheme. -`--aura-accent-contrast-color` **Read-only**:: -A color that has strong contrast when paired with `--aura-accent-color`. The contrast color is either pure white or a semi-transparent black, depending on the lightness of the accent color. +`--aura-accent-contrast-color` xref:./#read-only-properties[Read-only,role=badge]:: +A color that provides strong contrast against the `--aura-accent-color`, for example, button label color when the button background uses the accent color. The default contrast color is either white or a semi-transparent black, depending on the lightness of the accent color. -`--aura-accent-contrast-color-light` **Read-only**:: +`--aura-accent-contrast-color-light`:: The accent contrast color for the light color scheme. -`--aura-accent-contrast-color-dark` **Read-only**:: +`--aura-accent-contrast-color-dark`:: 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. - -`--aura-accent-text-color-light` **Read-only**:: -The accent text color for the light color scheme. - -`--aura-accent-text-color-dark` **Read-only**:: -The accent text color for the dark color scheme. - -.Define accent colors for the light and dark color schemes. +.Define accent colors for the light and dark color schemes [example] ==== -.Provide Enough Contrast -[CAUTION.small] -Choose a color that has at least 3:1 contrast ratio with the background color in your application. The accent color is used as is for the focus outline color, which needs to be visible for all users. - - [source,css] ---- -/* If you want, you can apply different colors for light and dark color schemes */ +/* You can apply different colors for light and dark color schemes */ html { --aura--accent-color-light: var(--aura-orange); --aura--accent-color-dark: var(--aura-purple); } ---- -.Using the orange accent color in the light color scheme and the purple accent color in the dark color scheme. -[.device] +.Using the orange accent color in the light color scheme and the purple accent color in the dark color scheme image::_images/accent-colors.png[] ==== @@ -244,15 +353,15 @@ image::_images/accent-colors.png[] Use any of the following class names on the `` element to set the accent color to the whole UI, or any component to set the accent color to only that part of the UI. -`.aura-accent-neutral`, -`.aura-accent-red`, -`.aura-accent-orange`, -`.aura-accent-yellow`, -`.aura-accent-green`, -`.aura-accent-blue`, -`.aura-accent-purple`. +- `aura-accent-neutral` +- `aura-accent-red` +- `aura-accent-orange` +- `aura-accent-yellow` +- `aura-accent-green` +- `aura-accent-blue` +- `aura-accent-purple` -.Use the purple palette color as the global accent color. +.Use the purple palette color as the global accent color [example] ==== [source,html] @@ -261,6 +370,25 @@ Use any of the following class names on the `` element to set the accent c ---- ==== +.Use the purple palette color as the accent color of a button +[example] +==== +[.example] +-- +[source,java] +---- + +var button = new Button("Generate with AI"); +button.addClassNames("aura-accent-purple"); +---- +[source,html] +---- + +Generate with AI +---- +-- +==== + == Surface Color @@ -272,29 +400,32 @@ image::_images/surface-colors.png[] [NOTE] If you need a background color that is darker than the base background color in the light color scheme and lighter in the dark color scheme, use the `--vaadin-background-container` and `--vaadin-background-container-strong` colors from the base styles. -`--aura-surface-color` **Read-only**:: -A computed color that you can apply to an element to give it elevation. The color is computed based on the `--aura-background-color` property, and adapts to the color scheme. The final value of the computed color depends on the effective values of the `--aura-surface-level` and `--aura-surface-opacity` properties. +[.property-table] +`--aura-surface-color` xref:./#read-only-properties[Read-only,role=badge]:: +A computed color that you can apply to an element to give it elevation. The color is computed based on the `--aura-background-color` property. The final value of the computed color depends on the effective values of the `--aura-surface-level` and `--aura-surface-opacity` properties. -`--aura-surface-level`:: -The “elevation level” of the computed surface color. Can be any fractional number, positive, or negative. Default is 1. In light mode, level 3–4 usually results in a white color in the light color scheme. In the dark color scheme, level 8 starts to be an upper limit, after which text colors are likely to not have enough contrast (depending on the surface opacity). +`--aura-surface-color-solid` xref:./#read-only-properties[Read-only,role=badge]:: +An opaque version of the effective surface color. Essentially the same as if `--aura-surface-opacity` was `1`. Useful for situations when a semi-transparent color is not suitable (e.g., when a surface needs to fully cover something). -`--aura-surface-opacity`:: -The transparency of the computed surface color. Defaults to 0.5. Transparency allows you to nest the same surface color on top of each other to create more sense of elevation. +`--aura-accent-surface` xref:./#read-only-properties[Read-only,role=badge]:: +A surface color that is tinted with the effective <<#accent-color,accent color>>. -`--aura-overlay-surface-opacity`:: -Surface opacity specifically for overlay elements. You can set this to 1 if you don't like the default semi-transparent overlays. +`--aura-surface-level`:: +The “elevation level” of the computed surface color. Can be any fractional number, positive, or negative. The default is `1`. ++ +With the light color scheme, levels 3–4 usually result in a white color, depending on the lightness of `--vaadin-background-color-light`. ++ +With the dark color scheme, level 8 starts to be an upper limit, after which text colors are likely to not have enough <<#contrast,contrast>> (depending on the surface opacity). -`--aura-surface-color-solid` **Read-only**:: -An opaque version of the effective surface color. Essentially the same as if `--aura-surface-opacity` was 1. Useful for situations when you need an opaque color. +`--aura-surface-opacity`:: +The transparency of the computed surface color. The default is `0.5`. Transparency allows you to nest the same surface color on top of each other to create more sense of elevation. -`--aura-accent-surface` **Read-only**:: -A surface color that is tinted with the effective accent color. === Customizing Surface Level & Opacity 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] @@ -318,7 +449,7 @@ Then, adjust the surface level with CSS, targeting the `input-field` part in the } ---- -.A comparison of the Text Field component with the default surface color and with an adjusted surface color level. +.A comparison of the Text Field component with the default surface color and with an adjusted surface color level [.fill.white] image::_images/surface-level.png[] ==== @@ -360,7 +491,7 @@ Then, adjust the surface level and opacity on the component element, and reset i } ---- -.A Checkbox Group component with a customized surface color applied on an internal part. +.A Checkbox Group component with a customized surface color applied on an internal part [.fill.white] image::_images/custom-surface-color.png[width=140] ==== diff --git a/articles/styling/themes/aura/index.adoc b/articles/styling/themes/aura/index.adoc index dff815f941..ac239cefc1 100644 --- a/articles/styling/themes/aura/index.adoc +++ b/articles/styling/themes/aura/index.adoc @@ -1,25 +1,135 @@ --- 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, <>). -[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. + +[[read-only-properties]] +.Customizable vs Read-Only Properties +[IMPORTANT] +==== +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 defined by `--aura-background-color-light` or `--aura-background-color-dark`, depending on the active color scheme (light or dark). 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. + +Technically, you can override these read-only properties, but then it's your responsibility to make sure all color combinations meet contrast requirements in both light and dark color schemes. + +Read-only properties are indicated on the Aura reference pages with the [badge]*Read-only* badge. +==== + +.Aura Does Not Use Lumo CSS Variables +[TIP] +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. + + + +== 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 <> 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 <>. + +.Use Component Variants +[TIP] +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, <> and <>. + +[source,css] ---- -@StyleSheet(Aura.STYLESHEET) -public class Application implements AppShellConfigurator { +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; } ---- -Explicit configuration is recommended for production applications so the theme choice is clearly documented in code. +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 <> and <> pages provide more details on targeting different UI elements. + +All Aura properties are listed on the <>, <> and <>. + + +=== Aura Theme Editor + +[.theme-editor-teaser] +video::/vaadin/videos/aura-theme-editor-teaser.webm[options="autoplay,loop"] + +++++ + +++++ + +The Aura theme editor allows you to visually explore the customization possibilities offered by the Aura style 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"] + + +== Using Aura to Style UI Elements + +You can use Aura properties instead of native CSS values to <>. This makes it easier to make them match the styling of Vaadin components, and to adapt correctly to light and dark modes. + +[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::[] diff --git a/articles/styling/themes/aura/other.adoc b/articles/styling/themes/aura/other.adoc index 19e6df354e..c536d76c37 100644 --- a/articles/styling/themes/aura/other.adoc +++ b/articles/styling/themes/aura/other.adoc @@ -1,6 +1,6 @@ --- -title: Other -page-title: How to style other visual component styles with Aura in Vaadin +title: Other Properties +page-title: How to use other Aura style properties in Vaadin description: Aura style properties related to sizing, spacing, corner shapes, shadows, and other visual styles. meta-description: Explore other visual styling options using the Aura theme in Vaadin. order: 40 @@ -8,18 +8,48 @@ order: 40 = Aura: Other Properties +== Density & Sizing + +[.property-table] `--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 + +[.property-table] `--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 + +[.property-table] `--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 `--aura-overlay-surface-opacity` is less than 1. + +`--aura-overlay-surface-opacity`:: +Surface color opacity for overlay elements. The default is `0.85`. diff --git a/articles/styling/themes/aura/typography.adoc b/articles/styling/themes/aura/typography.adoc index 78a0bdb2bc..182e725a49 100644 --- a/articles/styling/themes/aura/typography.adoc +++ b/articles/styling/themes/aura/typography.adoc @@ -8,20 +8,17 @@ order: 20 = Aura Typography -.Read-Only Properties -[NOTE.small] -Properties which are marked “read-only” aren't technically read-only. While you can override their values, the intention is to use them only to set values of other properties. - == Font Family +[.property-table] `--aura-font-family`:: -The font family used for the application. Set on the element. Defaults to `--aura-font-family-instrument-sans`. +The font family used for the application. Set on the `` element. Defaults to `--aura-font-family-instrument-sans`. -`--aura-font-family-system` **Read-only**:: +`--aura-font-family-system` xref:./#read-only-properties[Read-only,role=badge]:: The system font stack, where the default sans-serif font of the operating system is used. -`--aura-font-family-instrument-sans` **Read-only**:: +`--aura-font-family-instrument-sans` xref:./#read-only-properties[Read-only,role=badge]:: A font stack using the Instrument Sans font by default, and falling back to the system font stack if the web font fails to load. `--aura-font-smoothing`:: @@ -31,37 +28,63 @@ Set to `auto` to disable grayscale/anti-aliased font smoothing and use the defau == Font Size `--aura-base-font-size`:: -A number without a unit (i.e., _not_ a CSS length value) that represents the M size in pixels. +A number without a unit (e.g., `16` instead of `16px`) that represents the medium font size in pixels. The default is `14`. + +The base font size is used to compute the following font size properties. The font sizes are defined with the `rem` unit and rounded to the nearest full pixel size. + +[.property-table] +`--aura-font-size-xs` xref:./#read-only-properties[Read-only,role=badge]:: +Extra small font size. The default corresponds to `11px`. -The base font size is used to compute the following font size properties, which are defined with the `rem` unit and rounded to the nearest pixel size. +`--aura-font-size-s` xref:./#read-only-properties[Read-only,role=badge]:: +Small font size. The default corresponds to `13px`. -`--aura-font-size-xs`, -`--aura-font-size-s`, -`--aura-font-size-m`, -`--aura-font-size-l`, -`--aura-font-size-xl`. +`--aura-font-size-m` xref:./#read-only-properties[Read-only,role=badge]:: +Medium font size. The default corresponds to `14px`. -Aura supports the dynamic font sizing feature on iOS and iPadOS, which allows the user to set a font size preference in the OS settings. +`--aura-font-size-l` xref:./#read-only-properties[Read-only,role=badge]:: +Large font size. The default corresponds to `16px`. + +`--aura-font-size-xl` xref:./#read-only-properties[Read-only,role=badge]:: +Extra large font size. The default corresponds to `18px`. + +Aura supports the https://developer.apple.com/design/human-interface-guidelines/typography#Supporting-Dynamic-Type[Dynamic Type feature on iOS and iPadOS], which allows the user to set a font size preference in the OS settings. == Line Height `--aura-base-line-height`:: -A number without a unit (i.e., _not_ a CSS length value), relative to the corresponding font size. +A number without a unit (e.g., `1.5` instead of `24px`), relative to the corresponding font size. The default is `1.4`. + +The base line height is used to compute the following line height properties. The line heights are defined with the `rem` unit and rounded to the nearest 2 pixels. Each line height is designed to be used together with the corresponding font size. -The base line height is used to compute the following line height properties. The line heights are defined with the `rem` unit and rounded to the nearest 2 pixels. +[.property-table] +`--aura-line-height-xs` xref:./#read-only-properties[Read-only,role=badge]:: +Extra small line height. The default corresponds to `16px`. -`--aura-line-height-xs`, -`--aura-line-height-s`, -`--aura-line-height-m`, -`--aura-line-height-l`, -`--aura-line-height-xl`. +`--aura-line-height-s` xref:./#read-only-properties[Read-only,role=badge]:: +Small line height. The default corresponds to `18px`. + +`--aura-line-height-m` xref:./#read-only-properties[Read-only,role=badge]:: +Medium line height. The default corresponds to `20px`. + +`--aura-line-height-l` xref:./#read-only-properties[Read-only,role=badge]:: +Large line height. The default corresponds to `22px`. + +`--aura-line-height-xl` xref:./#read-only-properties[Read-only,role=badge]:: +Extra large line height. The default corresponds to `26px`. == Font Weight Static font weight properties. -`--aura-font-weight-regular`, -`--aura-font-weight-medium`, -`--aura-font-weight-semibold`. +[.property-table] +`--aura-font-weight-regular`:: +Regular font weight. The default is `400`. + +`--aura-font-weight-medium`:: +Medium font weight. The default is `500`. Used for input field labels, buttons, menu/nav/tab items, grid headers, etc. + +`--aura-font-weight-semibold`:: +Semi-bold font weight. The default is `600`. Used for headings and dialog titles. diff --git a/articles/styling/themes/index.adoc b/articles/styling/themes/index.adoc index 50c0045b70..a234e4e61a 100644 --- a/articles/styling/themes/index.adoc +++ b/articles/styling/themes/index.adoc @@ -1,5 +1,5 @@ --- -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. @@ -7,19 +7,37 @@ 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 <>. 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%] +[.device] +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. +<> 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%] +[.device] +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 +50,34 @@ 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 <> 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%] +.Login form using a customized Aura theme +[.device] +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. +<> 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%] +[.device] +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 +90,13 @@ 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 <> for a complete list. -.Login form using customized Lumo theme -image::../_images/lumo-theme-customized.png[Login form using customized Lumo theme, width=50%] +.Login form using a customized Lumo theme +[.device] +image::../_images/lumo-theme-customized.png[Login form using customized Lumo theme, width=360] [source,css] ---- @@ -91,7 +111,8 @@ html { The <<{articles}/styling/utility-classes#lumo-utility-classes, Lumo Utility Classes>>, when enabled, can be used together with the Lumo theme. -== Color Schemes +[[color-schemes]] +== Light & Dark Color Schemes Both Aura and Lumo support a light and dark color scheme. By default, the light color scheme is used. You can configure a different color scheme for the application by adding the [annotationname]`ColorScheme` annotation to your main application class. @@ -105,10 +126,11 @@ public class Application implements AppShellConfigurator { The color scheme enum supports the following values: -* `ColorScheme.Value.LIGHT`: Always use the light color scheme. -* `ColorScheme.Value.DARK`: Always use the dark color scheme. -* `ColorScheme.Value.LIGHT_DARK`: Use the light or dark color scheme based on the user’s OS or browser settings, with a preference for the light color scheme. -* `ColorScheme.Value.DARK_LIGHT`: Use the dark or light color scheme based on the user’s OS or browser settings, with a preference for the dark color scheme. +[.property-table] +`ColorScheme.Value.LIGHT`:: Always use the light color scheme. +`ColorScheme.Value.DARK`:: Always use the dark color scheme. +`ColorScheme.Value.LIGHT_DARK`:: Use the light or dark color scheme based on the user's OS or browser settings, with a preference for the light color scheme. +`ColorScheme.Value.DARK_LIGHT`:: Use the dark or light color scheme based on the user's OS or browser settings, with a preference for the dark color scheme. The color scheme can be changed dynamically at runtime using the [methodname]`Page.setColorScheme(ColorScheme.Value)` method. @@ -117,4 +139,15 @@ The color scheme can be changed dynamically at runtime using the [methodname]`Pa UI.getCurrentOrThrow().getPage().setColorScheme(ColorScheme.Value.DARK); ---- +.Testing Color Schemes with Browser DevTools +[NOTE] +==== +You can emulate the user color scheme preference in browser developer tools: + +- In Chrome, the Styles panel has a dropdown button with a paintbrush icon. +- In Firefox, the Styles panel has buttons with sun and moon icons. +- In Safari, the Elements panel has a dropdown button with a concentric circles icon. +==== + + [discussion-id]`6a974a47-d137-4d97-847c-80be46f011df` diff --git a/dspublisher/theme/global.css b/dspublisher/theme/global.css index 31289e0856..11dfe4984d 100644 --- a/dspublisher/theme/global.css +++ b/dspublisher/theme/global.css @@ -420,6 +420,11 @@ html[theme~='dark'] .card.card { word-break: normal; } +/* Allow inline code snippets to align on the baseline */ +[class^='ArticleLayout'] code { + overflow: visible; +} + /* * Work around a Chromium + MacOS issue with the scrollbar appearing on the * drawer scroll container whenever an overlay is open. @@ -456,6 +461,102 @@ body[style*="pointer-events: none"] [class*="drawerScrollContainer"] > * { border-top-color: transparent; } +/* Badge within plain text content */ +[class^='ArticleLayout'] .badge:is(.badge, :any-link) { + 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; + text-decoration: none; +} + +/* TODO exampleblock tweaks, should be in DSP */ +[class^='ArticleLayout'] .exampleblock.exampleblock { + margin-block: 2em; + + > .title { + border-bottom: 1px solid var(--docs-divider-color-1); + } + + .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); + } + } +} + +/* Custom definition/description list variant */ +.dlist.property-table dl { + border-radius: var(--docs-border-radius-l); + border: 1px solid var(--docs-divider-color-2); + gap: 0; + margin-block: 2em; + overflow: hidden; + + dt:has(.badge), + dt:has(.badge) + dd { + background-color: var(--docs-surface-color-2); + } + + @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; + margin-top: -1.5rem; + } + + dd { + margin-bottom: 3rem; + } + } + + dt code { + padding-inline-start: 0; + border: 0; + background: transparent; + font-weight: 600; + display: inline; + } +} + +.admonitionblock { + scroll-margin-top: calc(var(--docs-header-height, 3rem) * 2 + 1em); +} + /* Custom nav item styles */ /* "flat": don't indent the child items under the that parent item */ /* "reveal" (works only together with "flat"): show a handful of children even when the parent item is collapsed */ diff --git a/src/main/resources/META-INF/resources/vaadin/videos/aura-theme-editor-teaser.webm b/src/main/resources/META-INF/resources/vaadin/videos/aura-theme-editor-teaser.webm new file mode 100644 index 0000000000..1cab7c8656 Binary files /dev/null and b/src/main/resources/META-INF/resources/vaadin/videos/aura-theme-editor-teaser.webm differ