Skip to main content

All about Next Experience (Polaris) Themes Part 1

· 6 min read
Eric Riemer
ServiceNow Wizard

Next Experience Theming

When the new Next Experience UI came out with San Diego, everything about how to theme an instance changed. I have always liked making my instances look like "mine" or the company I worked for, so I was very interested in seeing what I could do with the new UI. This article is going to be the first in a series where I try to document all the things I know or have figured out about how to theme ServiceNow.

For some clarity, people tend to use the following pretty much interchangeably: Polaris, NEUI, Next Experience UI, NextUI, Next Experience, and Now Experience. To be technical about things:

  • Polaris: the default purple and black theme, Marketing would rather we don't talk about Polaris
  • Now Experience: the previous name for Next Experience
  • Next Experience: The new name for Now Experience
  • Now Design System (NDS): the entire modern UI layer that ServiceNow is using, this encompasses much more than the theme.
  • Next Experience UI (sometimes abbreviated as NEUI or NextUI): an attempt to specify just the UI and not include all components, workspaces and UI Builder
  • UX Theme: the actually correct term for a Next Experience Theme (and the label of the sys_ux_theme table)

Naming things is hard.

Background

Go watch the Live Coding Happy Hour talking about Overriding the Next UI Theme Things have changed since then and I know much more than I did then. If you are entirely new to dealing with Themes, this is likely the clearest place to start.

Aside

A few important notes.

  1. Look at the official docs for official documentation.
  2. Theme Builder exists. It is getting progressively better with each release, but right now I find it too limiting. It is 100% worth trying out to see if it suits your needs (because it is much much much simpler to use than anything I am going to show you).
  3. Check out the Next Experience Center of Excellence on Community for lots of great resources that include Theming and more about Next Experience.

Levels of Theming

There are three overall levels of using Themes.

  1. You like the default Next Experience (Polaris) theme and want Dark mode.
    This is the default and you do not need to do anything.

  2. You want to use your own colors but don't need Dark mode.
    Give Theme Builder a try and see if it suites you needs.

  3. Levels 1 & 2 don't suite you needs and you want more.
    You will be editing the JSON and defining things manually.

Don’t mix and match Theme Builder and manually editing themes. Anything you do outside of Theme Builder will not show up in Theme Builder and any changes you make in Theme Builder will overwrite what you did outside it.

I am only going to be digging deeply into Level 3 topics.

Theme Structure

UX Themes are made up of 1 or more JSON records holding CSS variables. Each JSON object can have 2 parts, Base and Properties.

The Base object is meant to hold values that are expanded into multiple numbered variables (no, I have not found anywhere that the variables that go here are documented). On the high end neutrals end up with 24 values, on the low end some only have 3-4.

For example this:

{
"base": {
"--now-color--primary": "79,82,189"
}
}

Would be the same as this:

{
"properties": {
"--now-color--primary-0":"209,210,238",
"--now-color--primary-1":"79,82,189",
"--now-color--primary-2":"53,55,128",
"--now-color--primary-3":"28,29,66"
}
}

The Properties object contains everything else. Primarily the object is used to map the base variables onto other variables. For example:

"--now-unified-nav_header--background-color": "--now-color_chrome--brand-10"

This means that when looking at a theme if there is something you want to change you may be working against a number of things. A color is controlled by a variable that is set to the value of another variable that is a variant of a defined color.

And it gets even worse… when you inspect the page to find the css property you want to change you are likely to find a variable, with a fallback variable, with a fallback value. And the variable that it is using is defined with another variable that is defined with a color.

background-color: RGB(var(--now-unified-nav_header--background-color,var(--now-color_chrome--brand-10,21,32,32)));

If we parse all of this out. We have CSS that says the background-color should be the RGB value stored in the variable --now-unified-nav_header--background-color unless that doesn't exist. In which case use the RGB value stored in --now-color_chrome--brand-10. If that also doesn't exist use RGB(21,32,32).

Since --now-unified-nav_header--background-color does exist we should use that color, which is set to be the same as --now-color_chrome--brand-10 in our theme (there is no need for the CSS fallback and the theme definition to match).

If we look in our theme (I am using the default Polaris theme in this example) we will not find a color that --now-color_chrome--brand-10 is defined as. What we do have is that the Base color --now-color_chrome--brand is set to 48,47,75 and that we want to use the #10 variant of that color.

(As of the Vancouver RTP release's theme engine that color is 24,24,38 but the calculation to get there has changed in the past and may well change again).

The natural thing to start wondering is "Which value do I change to get the Header color that I want?"

If all you want to change is the Header color, set a value for --now-unified-nav_header--background-color

If you want to change everything that uses that particular color, under properties set a value for --now-color_chrome--brand-10 (I do not recommend this).

If you want to change everything that is using any --now-color_chrome--brand colors, change --now-color_chrome--brand in base (even though that will mean you wont know exactly what #10 will look like in advance).

It can be a lot to wrap your head around.

Oh, and because Next Experience is made with components there is a lot of shadow-root. Which can make it very hard to actually find the element that has the CSS that controls the element you are looking at.

Upcoming parts to my theming series:

  • How I find stuff in the css
  • How the base color variations get generated
  • How I made my themes
  • Particularly useful properties
  • Dataviz colors (these are extra special)
  • Login Page Theming

Series

Part 1 <-- you are here

Part 2

Part 3

Part 4

Part 5

Part 6

Part 7