Color generation, Next Experience (Polaris) Themes Part 3

September 21, 2023 · 6 min read

ServiceNow Wizard

This is Part 3. You should start with Part 1.

How do the 'Base' colors get expanded?

In Part 1 I mentioned that theme JSON has 2 parts, Base and Properties, and that for some elements defined in Base they get expanded into some number of variations on that color.

How does that work? Which things can even be defined that way? Is there any way to know what --now-color--primary-2 will look like if I have defined --now-color--primary?

The answers are: It's tricky, it is undocumented (officially) but I can tell you what they are, and not really.

How do I know what a color is going to look like?

There are two choices. Either define a Base color and guess which variation of the color you should pick for things, or define each color in Properties.

I used to prefer defining each color in Properties, but I changed my mind. The primary reason I changed my mind is that the number of variations of some colors has changed between releases. That means that a theme will be missing some of the variations if you define them all yourself, but if you just set a Base color and let SN generate the variations they will always all be available.

Since the variables work in CSS anywhere in platform you could create a page (i.e. a service portal page) and have a series of elements that show you color swatches of all the colors. I would love to see someone do this, drop me a line if you come up with something.

Update:

After I initially posted this I discovered something useful. There is a way to get a copy of the JSON object with everything that your theme resolves to (the combination of all the UX Style records that apply to a theme or variant) with all of the Base properties expanded.

Install the Next Experience Developer Tools Chrome Extension.
Open your instance and open the Chrome Dev tools and select the Next Exp Inspector tab.
Scroll down the left column to find the line that starts with <sn-polaris-header
On the right side scroll down to availableThemes
This is an Array of objects that will contain an entry for your theme and all variants. The Properties object inside of that will have the full list of all the theme properties that will apply to that particular variant.

This is not the simplest or easiest way to find a particular key/value, but it works.

What can be defined in Base to get expanded?

This is completely unofficial, I may be missing stuff

Here are the Base colors and what they get expanded into.

--now-color--neutral: 0-21 (defining this seems to also generate values for the next 2)
	--now-color_surface--neutral: 1-6 
	--now-color_surface--divider: 1-6
--now-color--primary: 0-3
--now-color--secondary: 0-3
--now-color_selection--primary: 0-4
--now-color_selection--secondary: 0-4
--now-color--interactive: 0-4
--now-color--link: 1-4
--now-color--focus: 1-3
--now-color_alert--critical: 0-5
--now-color_alert--high: 0-5
--now-color_alert--warning: 0-5
--now-color_alert--moderate: 0-5
--now-color_alert--info: 0-5
--now-color_alert--positive: 0-5
--now-color_alert--low: 0-5
--now-color_surface--brand: 1-6
--now-color_chrome--brand: 0-10
--now-color_chrome--divider: 0-10
--now-color_grouped--blue: 0-5
--now-color_grouped--brown: 0-5
--now-color_grouped--gray: 0-5
--now-color_grouped--green: 0-5
--now-color_grouped--green-yellow: 0-5
--now-color_grouped--magenta: 0-5
--now-color_grouped--orange: 0-5
--now-color_grouped--pink: 0-5
--now-color_grouped--purple: 0-5
--now-color_grouped--teal: 0-5
--now-color_grouped--yellow: 0-5

This list and the variations are likely to change over time. As far as I know it is currently accurate, but that could change.

Things that seem like they should go in Base but don't

There are a bunch of numbered properties that start --now-datavis_color and --now-datavis_color--qualitative that really look like they should be in Base. They do not expand out if you put them there. This feels like an oversight that may get resolved in a future release. The now-datavis colors are used by "Platform Analytics" dashboards and data visualizations, but it's complicated and I am going to go into details in a future part.

How do the color variations work?

Officially, it is a black box. I am an employee and could dig into that black box and figure out how it all works, but then I couldn't tell you.

The good news is that we can see something very close to how it is actually done.

If you have been working on building a theme it is very likely that you have found a link to the deoprototypes site. Despite there not being any official branding, it is an actual SN site which will generate the JSON to use for making a theme.

Aside 1: The themes that it generates are based on an 'old' algorithm and do not match what SN will do with the same base colors (and it sometimes leaves out the full range of variations of a color). It can still be a great tool to use. Via experimentation I have proven out that the colors generated here do not match the color variations in a Vancouver instance.

The even better news is that the site is completely available to explore and pull apart because it is actually hosted on the ServiceNowDevProgram GitHub.

If you are interested in the 2200 or so lines of javascript be my guest. Based on the file naming I believe that the algorithm matches what was used in the San Diego release.

Aside 2: There is code here for generating dark themes, but it isn't called anywhere in the site, which is unfortunate.

Here is my understanding of the general way that color variations are generated.

Determine the "base" color that the base color will match (it isn't always the same variation number). This is done by converting the color to HSL, and taking the number of variations and multiplying it by L/100. The "base" color will be the total variations minus that number (or total - 1).
Loop through the number of light and dark variations and adjust the Saturation value of the HSL
Convert HSL back to RGB

I simplified this quite a bit, I would pick apart the code more, but I know that it isn't accurate for what is in production, so I am not too worried about it. Feel free to look at the code yourself if you want to actually understand it.

Dark mode themes work basically the same way, but it reverses the numbering (light themes get darker as the numbers go up, dark themes get lighter as the numbers go up). This is very useful to know/understand when building a dark theme.

Whats the deal with Neutrals?

It barely cares what I put in!

This is correct, the colors make almost no difference what you select for a neutral.

It takes the color you put in, changes it to HSL, sets S to no more than 5 and L to 35. This leaves you with a very slightly tinted set of colors at best.