Migrating from Lumo to Aura

Jmix 2 applications use Lumo, the only theme available in that version. Jmix 3 adds Aura and makes it the default for new projects, while continuing to support Lumo.

When you upgrade a Jmix 2 application, you can continue using Lumo or migrate the application to Aura. The migration covers differences in CSS custom properties, utility classes, and component theme variants. It also includes changes introduced by Vaadin 25: the theme resource location and the way stylesheets are loaded.

Complete the migration in the following order:

  1. Prepare Aura Files

  2. Update the Application Class

  3. Rebuild the Frontend Bundle

  4. Replace Utility Classes

  5. Replace Theme Properties (Optional)

  6. Review Component Customizations (Optional)

  7. Review Color-Scheme-Specific CSS (Optional)

  8. Remove Old Theme Files

  9. Test the Production Build

Prepare Aura Files

Create an Aura application theme directory:

src/main/resources/META-INF/resources/themes/my-project-aura
├── my-project.css
├── styles.css
└── view
    ├── login-view.css
    ├── main-view-top-menu.css
    └── main-view.css

Use the Aura files generated by a new Jmix 3 project as a starting point. In particular, use the generated Aura styles for the login view and main view instead of copying their Lumo styles without changes.

Move application-specific rules to my-project.css. In styles.css, place @import url('my-project.css'); after the imports for the generated view styles. This allows application-specific rules to override the generated styles.

Keep the old application theme in src/main/frontend/themes as a reference throughout the migration. Do not delete it until you have moved all required styles and completed the checks below.

Update the Application Class

Remove the @Theme annotation and its import. Add the Aura stylesheet stack to the main application class:

@StyleSheet(Aura.STYLESHEET)
@StyleSheet(JmixAura.STYLESHEET)
@StyleSheet("themes/my-project-aura/styles.css")

After this change, the application uses Aura. The old theme directory is no longer active, but keep it as a reference for the remaining migration steps.

Rebuild the Frontend Bundle

An upgraded application may contain a frontend bundle generated before the theme migration. In this case, the application can load the Aura stylesheets while some components still use Lumo styles, making the interface look inconsistent.

Clean the generated Vaadin frontend files:

./gradlew vaadinClean

Then start the application in development mode. Vaadin generates a new development bundle using the current stylesheet annotations and theme files.

Replace Utility Classes

Aura does not include Lumo utility classes. Replace LumoUtility constants and class names with one of the following:

  • Theme-independent constants from io.jmix.flowui.theme.StyleUtility.

  • Component properties or component APIs.

  • Custom CSS classes defined in the Aura application stylesheet.

For example, a Jmix 2 main view uses Lumo utility classes to position userMenu:

Jmix 2
<userMenu id="userMenu"
          themeNames="tertiary"
          classNames="ms-auto me-m">

Replace them with the class used by the generated Aura main-view styles:

Jmix 3 with Aura
<userMenu id="userMenu"
          themeNames="tertiary"
          classNames="jmix-main-view-user-menu">

Replace Theme Properties (Optional)

Check any custom CSS files in the old theme. Complete this step if these styles define or reference Lumo CSS custom properties with the --lumo- prefix.

Replace these CSS custom properties with Aura or common Vaadin properties according to their purpose. There is no direct replacement for every Lumo property.

Lumo customization Aura approach

Primary color

Set --aura-accent-color-light and --aura-accent-color-dark.

Application background

Set --aura-background-color-light and --aura-background-color-dark.

Font family and size

Set --aura-font-family and --aura-base-font-size.

Border radius

Set --aura-base-radius or a component property such as --vaadin-button-border-radius.

Component size

Set --aura-base-size or a component-specific --vaadin- property.

See the Aura theme reference for the complete list of Aura properties.

Do not mix --lumo- and --aura- properties in new CSS. Use common --vaadin- properties when the same rule should work with both themes.

Review Component Customizations (Optional)

Complete this step if custom application stylesheets contain CSS rules for components, or if XML view descriptors or Java code apply component customizations.

Review the following for each customized component:

  • Component theme variants. Check the UI component reference to see which variants are available for a particular component and whether they are supported by Aura, Lumo, or both themes.

  • Java constants with the LUMO_ prefix. Replace them with theme-independent equivalents when available.

  • Rules in the old src/main/frontend/themes/<theme>/components directory.

    Vaadin 25 disables CSS injection from the src/main/frontend/themes/<theme>/components directory by default. Move these rules to a regular application stylesheet. Use component properties, shadow parts exposed through ::part(), state attributes, or other documented selectors.

Review Color-Scheme-Specific CSS (Optional)

Complete this step if the application contains custom light- or dark-mode styles.

Review rules based on html[theme~='dark']. This selector works with the Jmix ThemeUtils mechanism and with ColorScheme.Value.DARK because both set the theme attribute. It does not work with the Vaadin system modes, LIGHT_DARK and DARK_LIGHT, which use the CSS color-scheme property instead.

Use the CSS light-dark() function for colors that must work in all modes. See Writing Color-Scheme-Aware CSS.

Remove Old Theme Files

After migrating the application-specific rules, utility classes, component styles, and color rules, you can safely delete the old src/main/frontend/themes/<theme-name> location.

Test the Production Build

Test both development and production modes after moving the theme files.

For a JAR deployment, build the application in production mode:

./gradlew -Pvaadin.productionMode=true bootJar

Start the application and verify that the application stylesheet and custom styles are applied.