How to Create a Multicolored Theme for a Modern SharePoint Online Site

Last updated on September 3, 2023

In November 2017, Microsoft released a new site theming capability for the modern SharePoint sites in Office 365. It came with eight out-of-the-box themes you can choose from, and you can also create your own themes using the Theme Designer App.

Using the theme designer app is easy. All you need to do is to first choose one primary color, a text color, and a background color from, e.g., your company’s brand guidelines document. Then paste their hex values into the generator, click the Export theme button in the top right corner, copy the generated color palette from the PowerShell tab, and deploy it to your tenant using PowerShell. If this is your first time creating a theme and you want to see how all of this works in practice, watch my video Getting started on using modern themes in SharePoint Online below.

But what if your organization has multiple brand colors, and you would like them all to be visible? I’ve already run into this kind of a situation a few times, and usually three different colors should all be equally apparent.

At first, you would think that you can include a secondary and a tertiary color just by inserting their hex values into the “themeSecondary” and “themeTertiary” tokens in the color palette. However, a quick test revealed that it is not the case. So, I started investigating, what effect each of these tokens has on a modern site?

Table of Contents

1. Investigating the effects of the theme tokens
2. The findings
3. Where the tokens occur
4. Creating a multicolored theme
5. What has changed from a year ago?
   1. The header background color
   2. The theme generator
   3. Adjustments to tokens
6. Afterword

Investigating the effects of the theme tokens

When I started investigating, I came accross this piece of information that the color palette generated by the theme generator doesn’t actually include all the available tokens. This is simply because a lot of the tokens don’t have any effect on a site.

However, I didn’t want to leave them outside of my research scope, so I decided to include them as well. To see the complete list of available tokens, I opened the developer tools panel in my browser (F12) and ran window.__themeState__.theme in the console tab.

I created a color palette with all the available tokens and as distinctive colors as possible. The result was not meant to be pretty but to help me easily distinguish where each of the tokens are used. Below is the result. I’ve written down the color names for the tokens that I noticed to be visible.

@{
# included in theme generator
"themePrimary" = "#e55342" #Strawberry 
"themeLighterAlt" = "#888EA8"; #Dark lavender
"themeLighter" = "#efe6f2"; #Light lavender
"themeLight" = "#796722"; #Olive
"themeTertiary" = "#994719"; #Sienna
"themeSecondary" = "#AD4361"; #Raspberry
"themeDarkAlt" = "#FBC0C3"; #Pink
"themeDark" = "#80B88C"; #Dark Mint
"themeDarker" = "#FFB29A"; #Light salmon
"neutralLighterAlt" = "#136D80"; #Teal
"neutralLighter" = "#e8fffd"; #Light turqoise
"neutralLight" = "#765A4F"; #Coffee
"neutralQuaternaryAlt" = "#8A5E72"; #Dark plum
"neutralQuaternary" = "#016d28"; #Pine
"neutralTertiaryAlt" = "#ffd9bf"; #Light orange
"neutralTertiary" = "#ffcc01"; #Yellow
"neutralSecondary" = "#9aabb2"; #Gray
"neutralPrimaryAlt" = "#9C000C"; #Maroon
"neutralPrimary" = "#53C7BD"; #Turqoise
"neutralDark" = "#F4843E"; #Orange
"black" = "#000000"; #Black
"white" = "#ffffff"; #White
# no longer included in theme generator
"primaryBackground" = "#FFF7D7"; #Light yellow
"primaryText" = "#72BD54"; #Lime
"bodyBackground" = "#ffbf40";
"bodyText" = "#593c00";
"disabledBackground" = "#CD9D7C";
"disabledText" = "#52834C";
# never been included in theme generator
"backgroundOverlay" = "#102542"; #Navy
"whiteTranslucent40" = "rgba(255,255,255,.4)"; #White translucent
"accent" = "#f87060"; #Coral
}

Click here to download the complete palette (.zip)

The findings

What I immediately noticed when browsing through the sites was that some of the tokens are a lot more dominant than others, some tokens are only used at particular places, and a lot of them I did not encounter at all. Also, to achieve a good color contrast, some tokens are meant to have lighter color values (backgrounds), while some others are expected to use darker colors (texts, icons, etc.). Unless you wanted to create a very dark theme, in which case those would be reversed.

I also noticed that the system pages use the same color theme as well but in a different way. This can make it hard to come up with an excellent looking multicolored theme if the system pages are also required to look good and branded. On the other hand, if you find a good color combination for the system pages, you could use the color theme also on classic sites; though you need to apply the palette on them programmatically, e.g., via site templates.

There are also two other more recent changes that didn’t exist yet when I originally wrote this blog post in January 2018 and which make it even harder to find a multicolored theme that would look amazing in all situations:

• The “Site contents” view uses the same color theme but differently. For example, the document library primary background color comes from the same token as the header background color, and the cogwheel dropdown doesn’t use the same colors as when browsing pages.
• Some web part elements get their colors from different tokens depending on the chosen section background color. This means that you need to test your color theme on all of the different section background colors and ensure that web parts look nice on all of them. The same applies to the header elements if you change the header background color via the “Change the look” panel.

Here is a picture where all of the different section backgrounds are used. If you compare the Quick links web part icon to the icon in the earlier image of a communication site, you can notice that the background color is different because another section background color is used.

Where the tokens occur

In addition to the tokens offered by the theme generator, I did find a couple of tokens, that are not included but which have a minimal effect on the modern sites: “accent” and “whiteTranslucent40”. And then a more recent discovery and a huge thing a lot of people had already been asking about: the new header background color — “backgroundOverlay”.

Here’s a complete list of my findings:

Creating a multicolored theme

How should I then create a multi-colored theme based on these findings? I don’t think there is a one-size-fits-all solution when it comes to this; it always depends a bit about the colors you are working with. However, I can give you an example of how I’ve approached the problem.

For this example, I picked three distinctive colors: navy, coral, and turquoise – just because I thought they looked good together. First, I generated a base for my theme using the navy color, a dark gray text color (#6f6f6f) and plain white (#fff) as the background color. Then I started to plan, which token values I would replace with coral and turquoise.

Because the coral is quite a bright color and I wanted it also to be clearly visible, I looked for tokens I had marked as darker and dominant. I could have selected one of the tokens used for texts, but because I instead wanted to use the color in icons, I opted for two more subtle tokens instead: “themeDarkAlt” and “themeDark”. I also added it as the “accent” color for a nice touch in the Change the look panel.

The turquoise was a bit harder to place because it isn’t exactly a dark color, nor is it light enough to be used as a background color. In the end, I decided that it would be suitable as web part texts, so I included it in the “neutralSecondary” token.

After a little bit of testing, I noticed I could use a lighter shade of coral at some places (e.g., the hover background color in select web part panel) instead of the light blue color generated based on the navy blue color. I created a new theme in the theme generator using the coral value and picked two of the generated values to use instead of the originally created blue values (themeLighter, themeLight). I also considered making a lighter shade of the turquoise color and using it as the background color in the “neutralLighter” token, but eventually decided against it, because it might have made the turquoise color too dominant compared to the other two colors.

Now that we can also include the header color option, I added the “backgroundOverlay” token to my color palette and used the same navy color that I had chosen as my primary color. The down side of setting the header color to a very dark one this way is that the text color doesn’t get changed to a lighter one. To accomodate this, I adjusted the “neutralPrimary” token color to be a more medium gray shade instead of a dark one. The same token is used also by a lot of different text elements, so I didn’t want to change it to a very light shade either.

Finally, I deployed my custom theme using the PowerShell script below. Note that these days you can also deploy themes using PnP provisioning templates (tenant wide deployment).

$adminSiteUrl = "https://mytenant-admin.sharepoint.com"
$themeName = "Multicolored theme"
Connect-SPOService $adminSiteUrl

#Uncomment if you want to update an existing theme
#Remove-SPOTheme -name $themeName

#Replace the variable value with the generated code
$palette = @{
    "themePrimary" = "#102542"; #Navy
    "themeLighterAlt" = "#d3dce8";
    "themeLighter" = "#fee7e5"; #Coral, themeLighter
    "themeLight" = "#fdd3ce"; #Coral, themeLight
    "themeTertiary" = "#7088aa";
    "themeSecondary" = "#567095";
    "themeDarkAlt" = "#F87060"; #Coral;
    "themeDark" = "#F87060"; #Coral
    "themeDarker" = "#1c3557";
    "neutralLighterAlt" = "#f8f8f8";
    "neutralLighter" = "#f4f4f4";
    "neutralLight" = "#eaeaea";
    "neutralQuaternaryAlt" = "#dadada";
    "neutralQuaternary" = "#d0d0d0";
    "neutralTertiaryAlt" = "#c8c8c8";
    "neutralTertiary" = "#d4d4d4";
    "neutralSecondary" = "#53C7BD"; #Turquoise
    "neutralPrimaryAlt" = "#818181";
    "neutralPrimary" = "#8c8c8c";
    "neutralDark" = "#555555";
    "black" = "#3f3f3f";
    "white" = "#ffffff";
    "accent" = "#F87060"; #Coral;
    "backgroundOverlay" = "#102542"; #Navy
}

Add-SPOTheme -Name $themeName -Palette $palette -IsInverted:$false -Overwrite

And that’s it! A nice looking multicolored theme, using the colors I chose.

Now, if you want to automatically apply your custom color theme to new modern SharePoint sites, check out my Ultimate Guide to SharePoint Site Templates and Site Scripts for instructions.

What has changed from a year ago?

I originally wrote this blog post in January 2018. A lot has changed since then and more changes will come. I will most likely have to update this blog post again in the future, but here’s what changed in a year after this blog post was originally published.

The header background color

The option to change the header background color is a very recent addition. I already got a few comments about people trying to find which token was responsible for changing the site header background color, and finally, I spotted it while doing this major update for this blog post.

The token is called “backgroundOverlay”, and most likely the reason why it wasn’t spotted earlier is that the color doesn’t come into effect immediately when you apply the theme; you need to refresh the page! The same thing also happens if you ever go back to the “Change the look” panel and switch around the settings — luckily refreshing the page does the trick this time as well.

The downside of setting the header background color via a color palette is that the header text color doesn’t get changed at the same time like it does if you change it via the “Change the look” panel. The text color is still set based on the “neutralPrimary” token which is used by a lot of other texts too. If you want to achieve a good color contrast between the background and the text in all the places, you need to aim for a good medium shade color.

There’s also another way for adjusting the header background color if you are already setting the theme on sites programmatically or want to adjust the header layout, too. The SharePoint web object contains information on what header settings have been selected, and you can adjust those with, e.g., PowerShell.

$webUrl = "https://mytenant.sharepoint.com/sites/sitename"
$themeName = "Multicolored Theme"
$headerLayout = "Compact" # Standard or Compact
$headerEmphasis = "Strong" # None, Neutral, Soft or Strong

Connect-PnPOnline $webUrl #-UserWebLogin # Uncomment if you use MFA

Set-PnPWebTheme -Theme $themeName

$web = Get-PnPWeb
$web.HeaderLayout = $headerLayout
$web.HeaderEmphasis = $headerEmphasis
$web.Update()
Invoke-PnPQuery

For running this script, you need to have the PnP PowerShell commandlets installed. You can install those with the following command (run the shell as administrator).

Install-Module SharePointPnPPowerShellOnline -AllowClobber

And if you can’t see the properties in the web object, you need to update the module as follows.

Update-Module SharePointPnPPowerShellOnline

You can browse all the properties that are related to the web object, e.g., in the Windows PowerShell ISE (type $web. on the command line to open the menu). Other properties you might be interested in setting at the same time are SiteLogoUrl, and also FooterEnabled and MegaMenuEnabled on communication sites.

The theme generator

When I originally wrote this blog post, Sean Squires confirmed my suspicions on Twitter that the theme generator was indeed going to be improved!

Great write up @LauraKokkarinen – thanks for sharing! Yes, more options to come – along w/ improvements to the theme generator tool to make color choices clearer. https://t.co/Cxij1Dq6G6

— Sean Squires (@iamseansquires) January 23, 2018

And it did. For a few months, you could select different colors for different tokens right in the theme generator by clicking the little squares below the main color pickers.

In the beginning of May 2019, the theme generator – or should I say Theme Designer App – was updated again and moved to a new location. You can no longer select colors for individual tokens via the color pickers, and have to fall back to the old method of inserting the hex values directly to the script. The good thing is that you can now see how the colors appear for the different components.

However, it still doesn’t help with the original dilemma: where do each of the different tokens appear on a SharePoint site? And how do the component colors change if the section background color is altered? I don’t know if the theme designer app will ever give a straight answer to these questions because the color tokens seem to be in constant flux, and keeping things up to date all the time would require a lot of work. Luckily, we can still achieve the desired result by putting in a little bit of extra effort as described in this blog post.

Adjustments to tokens

During the past year, I got reports from people in the comments that some of the tokens were no longer used in the places where they used to. Changes to the modern themes are inevitable and I knew that I had to update this post sooner or later. And because I could no longer trust my earlier findings, it meant doing the whole research all over again.

In the end there were not too many changes to the tokens. There were a few of cases where an element now received its color from another token than originally reported; the most notable one being the main background color. There were also a couple of tokens that weren’t previously used anywhere that now have a small effect, and also the new header background color.

Afterword

Have you created any custom themes yet? What are your experiences? Do you have some good tips and tricks to share, or have you perhaps noticed some token value used in a place not yet mentioned in this post? Let me know in the comments below! Also, if you found this article useful and would like to read similar content in the future, follow me on Twitter to be notified of future posts. Thank you so much for reading, it means a lot to me, and until next time!

Laura