As a Vaadin Designer, I spend a lot of time theming Other People’s Apps. Unfortunately, as I have learned over the years, many people seem to end up building apps that don’t like to be themed. If you, however, want to reduce the time and effort needed to theme your app, then here are some best practices that you can follow.
Have a plan
Don’t start coding the UI before making at least some kind of design for it. This can be as simple as sketching some wireframes or mockups. This way, your components will already be roughly in the right place for any visual or graphic design that will be developed later. Otherwise, be prepared to do some serious refactoring before your screens can be themed the way they look in the final design.
Name all the things
Give style names to all your components. Yes, that includes layouts, panels and your own custom components. Every component that’s missing a style name will significantly decrease the ease and precision with which your app can be themed.
Add style names to your components by calling addStyleName(String) on them. This is preferred to calling the other style name method that starts with “set”, because calling addStyleName(String) does not let you accidentally remove style names that were added earlier.
Choose style names like you would choose variable or class names. You want your style names to be semantic, meaningful and independent of what your components will be styled like. Your style names merely define hooks for your style sheets and should leave the implementation specifics up to the theme itself. Only components that are functionally the same should get the same style name.
Never pass your style names directly as string literals. Always define them as constants in a single theme class that is named after your app. This way, your theme class becomes an explicit API through which the UI code and theme CSS can communicate.
Come up with a unique prefix for your app’s style names. That way, you will avoid name clashes with other people’s style names. However, do not use the “v-” prefix for your own work, because that one is reserved for Vaadin’s internal use only.
Give each unique component a unique ID, with setId(String). Giving a component an ID makes it much easier to theme than merely giving it a style name alone. For coming up with an ID, use the same rules as you do for style names. Note that it is your own responsibility to make sure there will never be more than one component with a given ID on-screen at the same time!
Keep it simple, stupid
Stick to Vaadin’s off-the-shelf components whenever you can. Always try to solve your problems with server-side composition before resorting to client-side code. Don’t create custom components unless you absolutely have to. The less standard your components are, the harder it will be to figure out how to theme them.
When you do write client-side code, include as little CSS as possible. Ideally, your custom component should have only the bare minimum of CSS required to make it function at all. Any further styling of your component should happen in the theme. Avoid the temptation to style your component to make it look at home in a specific theme, because that will make it that much harder to modify your theme. The more built-in CSS styles your component has, the harder it becomes for a theme to override these.
Keep the complexity of your UI code low. Whenever possible, prefer a shallow component hierarchy. If you are having a hard time to get a certain piece of your UI to work the way you want it to, then you might have just chosen the wrong components for the job. So, always consider going back and trying if a different composition of components could solve your problem more easily. The more complex your UI code is, the harder it will become to theme.
Don't get ahead of yourself
Don’t theme your layouts until the implementation of your views has stabilized. The nature of CSS is that it is very tightly coupled to the DOM structure. Therefore, as long as you are still moving your components around in your app, it’s way too easy to break your layouts while doing so. Stick to theming only the individual components at first and do off-the-shelf ones before custom ones.
Focus on the functionality first. Everything in your app should be able to work without having been themed yet. That not only enables to leave the theming until the very end, but additionally it ensures that your UI code won’t have any implicit dependencies on your theme implementation.
Conclusion
Not many people realize how to make their app more themable, but doing so does not actually require much extra work. Follow these steps and you will end up saving yourself a lot of headaches down the road.
Marlon Richert works as a Designer at Vaadin, helping its customers design and implement awesome UIs that make you and your bosses happy with first-class user experience. Learn more about how Vaadin can help your business at https://vaadin.com/services.