I’ve built an application that currently uses a lightly customized version of the Lumo theme. Most of the customizations are related to a nested router layout setup and some color adjustments.
I recently experimented with Vaadin 25-rc2 and the Starpass demo, and I really like the look and feel of the new Aura theme. However, when I tried enabling Aura on a test branch of my application, the UI looked quite off, which I expected given the existing Lumo-based customizations.
Will there be an official guide or documentation published on migrating from Lumo to Aura once Vaadin 25 is released?
If not, I’d appreciate any guidance or best practices from those who have already explored this migration.
Hi! Thanks for the question, and for trying out Aura.
I’d be interested in seeing a comparison, screenshots of your app with Lumo and then with Aura, if possible.
Have you used Lumo CSS utility classes in your app?
If you haven’t done much customizations on top of Lumo, I would assume the app should look quite okay with Aura as well. But we most probably have missed some details, so please share some more details what things are “off” in your opinion.
I am doing the same right now for one of my apps, who I also built with the starpass theme in V24.
The biggest pain is the replacement of LumoUtilities, as there is no real replacement, except for Tailwind, which works fine, but does not align with Vaadin/Aura styling variables at the moment, e.g. there is no dedicated class for --vaadin-padding-m - you either need to use the respective numeric tailwind classes ( p-2) or the custom-var-classes (p-(--vaadin-padding-m), which can lead to some unreadable code).
I did the following, so it may help you finding your own way:
move the content of your themes folder to the respective new position under META-INF/resources (and maybe some subfolder like styles)
remove the @Theme annotation and add the respective @Stylesheet annotation
a. either add the aura import in your styles.css or as an extra annotation
go through your css files and replace the --lumo properties with the respective --vaadin or --aura properties (see Vaadin themes and base styles for details). It is a bit more tedious to find the correct prefix, since now it is one of the both with --vaadin the more prominent one (at least for my code it was the case)
a. you will see, that there are no “margin” variables anymore. I used the “padding” ones also for margins.
b. there are also no “sizes” anymore (like --lumo-size-m). If you used them, you have to create them yourself.
And now the potentially ugly part: if you have used LumoUtility (I did that a lot for instance), you have to decide, how to overcome them
a. either by converting all the respective settings into css in stylesheets. I started with that first and it was very very tedious. But it keeps the Java code a bit cleaner, since you only have a single css class there.
b. or by replacing them with Tailwind css classes. This is my current approach. It bloats the Java code a bit more with a lot of strings, especially since it is more powerful and there a no constants, but it speeds up the conversion process, since you do not have to create a lot of additional stylesheets. When that part is done, often used Tailwind classes can be converted into static Strings, that can be reused and are a bite more self explanatory.
c. when using Tailwind, I would recommend to map the variable custom vars (like Padding.S, .M, etc) to the numeric tailwind classes (like p-2, p-3, …) - or, if you want to use p-(--vaadin-padding-m), convert them directly into String constants.
Some components may look different, for instance the progress-bar IIRC looks a bit different in Startpass than in Aura. If that is the case, peek into the respective Starpass styles and pick styles you need for your app
Check everything and fix potential issues.
Side notes:
Most important side note: depending on the amount of styles, it may take a while until the conversion is done. Don’t try to fix things, until you have converted everything. I did that cause I was to impatient and it lead to duplicate styles at some points.
Aura handles “primary” colors differently than lumo. There is not a “primary” color, but an accent color, that behaves differently. Depending on the accent color, that can have interesting side effects (my primary color was pink-ish, which did not fit well as accent color). So you may have to override the aura accent color property for dedicated parts or components of your app.
Light and dark themes are configured differently than in Lumo. Always use the -dark/-light variant of a custom property.
Be careful with the background color to pick. It affects a lot in Aura, more than in Starpass IIRC.
I hope I did not forget anything, but this is more or less a “log” of my doings and I took some turns before I found a way that worked fine for me.
Unfortunately I can’t share screenshots in a public forum due to certain elevated compliance requirements for the application I work on.
Most of the visual oddities are related to padding and spacing which is causing the UI to look “squished”
I’ve used LumoUtility in a few places and I’ve modified a lot of the Lumo CSS Selectors to match my branding. I also use a custom router layout as opposed to standard AppLayout.