UX Theme records, Next Experience (Polaris) Themes Part 2
This is Part 2. You should start with Part 1.
How do the UX Theme records work?
Any theme is made up of a few different things.
- The UX theme
- 1 or more UX styles (which may be core or variant)
- UX theme styles
- Assets
UX Theme
The UX Theme record is the overall container. This one is simple.
UX Style
The UX Style contains the JSON that stores the CSS variables. If it is Core it will always apply and be part of the “default” theme. If it is a “variant” it will be selectable as an alternate colors set.
UX Theme Style
The UX Theme Style is the m2m record that links the theme and style. It also has two important fields. First is “Audience”, which controls who has access to that style. For example, you could have a variant only available to certain users or even force a core theme to apply for certain users. Second is “Weight”, which controls when something should apply. The weight works the same way as many other places in the platform. A weight of 0 will always apply, unless something with a higher weight overrides it. Unlike elsewhere in the platform weight does not work at the record level. Rather when the theme is resolved into values it is a variable by variable comparison of weight.
This is not official information, it is what I have observed by experimenting.
This means that if there are 2 styles that both define the same variable, the one with the largest weight will apply. As an example if you make a core theme with a weight of 100 and a variant with a weight of 10, nothing defined in the variant that is also defined in core will apply.
I plan to talk more about how I structure my themes in another article, but here is a practical example. There are a lot of variables that need to be mapped to something in order to not just use a default value. If you want your login page to match your instance theme you need to set up those mappings. I mapped those out in a UX Style that I could reuse across multiple themes, and I give it a weight of 0. When I make a La Jolla inspired theme, the login page was… ugly. So in my La Jolla Style I added some of the login page variables, and gave that style a larger weight. This way the login page looks “good” and if someone decides to change the Core style to one of the variants everything will still work and look good.
Assets
The final thing that makes up a theme are Assets. These are typically attachments that are used with your theme. The most common one is the logo image. The default Polaris theme also includes some custom fonts as assets.
Polaris tour
Combining what we went over in Part 1 and 2 lets take a look at the Polaris theme to see how this all applies.
We can start by ignoring some of the things I mentioned above. None of the styles have an Audience or Weight.
In Vancouver, there are 7 UX Styles that make up the theme.
Dark
This is the dark mode variant of the Polaris theme. This is a good reference point to see how to make a dark mode theme.
Mobile Colors Default
This is the style that can apply to the Mobile app. It only applies to the mobile app and not the instance in a mobile browser. It will also only apply to the mobile app if your theme is also set as the mobile theme in the App's config (in your instance go to System Mobile > Mobile Branding > Mobile App Configs and then set the Mobile Theme to a UX Theme that contains the style you want to apply).
Since almost everything in this record is a reference to another variable, just including this Style into your own Theme is enough to make your Theme apply to your mobile app.
UI16 Dashboard Visualization Compatibility
I have not dug around to see where these colors are actually used (if anywhere), but it seems like the safest idea to include this in any custom themes as well. Themes generated by Theme Builder do not include it, which leaves me questioning if it is actually necessary or not.
Shape and Form
This style holds most of the values that define things like how curvy the corners of buttons are. It also has some other stuff like border width and some opacity settings.
This is one of the places where you can take instance theming to really advanced places, but you really need to know what you are doing.
Imagery
This is an easy one. it defines the header logo.
The header logo is actually a weirdly complicated thing to deal with sometimes.
If you set the Property glide.product.image.light it will update the header logo without touching the UX Theme in any way. This is the same as going to System Properties > Basic Configuration UI16. The officially documented method involves editing the My Company record. Pre-vancouver, when using Theme Builder you would need to set the glide.ui.polaris.theme_builder.override_logo property.
It can all be very complicated. I am hopeful that this will get clearer and simpler over time.
Typography
This style contains most (but not all) of the typography definitions. Which font to use, what sizes and weights etc. It also has associated Assets with the attached .woff2 web fonts.
Colors
Finally we get to the big one. The core Colors for the theme. In it you will find over 1300 lines to color definitions and mappings (mostly mappings).
This is where your custom Theme is going to start diverging from the default Polaris theme. IMO, if you are making a custom theme it is smart to include the rest of the Core Styles in your theme to make your life easy. Including this one can be a mixed bag.
On the side of "Yes, include it and override things", this record should always have all of the most up to date color mappings. every single family release since Polaris has come out has added additional style hooks that need to be mapped. It is way simpler to let something new automatically be set to --now-color_chrome--divider-3 than wonder why something suddenly looks weirdly ugly and clashes with your theme.
On the other hand, not everything that gets added is mapped to another color. Some things are going to be new and hard coded to a specific color. Which will also make things look weirdly ugly and clash with your theme.
For my themes I decided to go with creating a new Style that has all of the Polaris color mappings and when a new family release comes out doing a diff to see what has been added (or removed, that happens too). Even though it can be extra work to update my record, it also means that I have more control and know what to look out for with things changing. It also means that in my themes I only need to deal with >200 lines in each of my Style records (depending on what I want to override) instead of 1300+. Since I like making Themes, having a bunch of reusable records is a big plus to me.
Series
Part 2 <-- you are here