Skip to content

Custom SharePoint theme

A SharePoint theme is a named colour palette stored in the tenant. bdoctor publish --applyTheme applies the theme named in siteDesign.theme, but it never creates or updates one, so a custom theme has to be registered in the tenant first. That takes three steps:

  1. Create the palette.
  2. Register it in the tenant.
  3. Apply it to the site.

A built-in SharePoint theme (Blue, Orange, Red, Purple, Green, Gray, Dark Yellow or Dark Blue) needs none of this: set its name in siteDesign.theme and pass --applyTheme. The newer default themes in the SharePoint theme picker, such as Teal, Periwinkle, Cobalt and Dark Teal, are not in that list, as the CLI for Microsoft 365 does not know them by name; a site owner picks them under Settings > Change the look.

A theme is 22 colours plus an isInverted flag that marks a dark theme.

  • The accent: themePrimary and its shades, themeLighterAlt to themeDarker. SharePoint uses them for links, buttons, selected navigation, and the header and footer backgrounds that the siteDesign.chrome emphasis settings pick.
  • The neutrals: white is the page background, neutralPrimary the body text, neutralSecondary the secondary text, and the rest are borders and surfaces.

Fonts, layout, the logo and the header layout are not part of a theme; siteDesign.logo and siteDesign.chrome set those. The Better Doctor Markdown web part follows the site and section theme for its text and surfaces, while its code blocks take their colours from markdown.theme.

A palette file is a flat JSON object of # hex colours. This is the light Better Doctor theme, built from the brand teal:

{
"themePrimary": "#117466",
"themeLighterAlt": "#f1f9f8",
"themeLighter": "#c9e9e4",
"themeLight": "#9fd5ce",
"themeTertiary": "#54ab9f",
"themeSecondary": "#218476",
"themeDarkAlt": "#0f675c",
"themeDark": "#0d574d",
"themeDarker": "#0a4039",
"neutralLighterAlt": "#f8f8f8",
"neutralLighter": "#f4f4f4",
"neutralLight": "#eaeaea",
"neutralQuaternaryAlt": "#dadada",
"neutralQuaternary": "#d0d0d0",
"neutralTertiaryAlt": "#c8c8c8",
"neutralTertiary": "#a6a6a6",
"neutralSecondary": "#666666",
"neutralPrimaryAlt": "#3c3c3c",
"neutralPrimary": "#333333",
"neutralDark": "#212121",
"black": "#000000",
"white": "#ffffff"
}

The sample repository carries it as bdoctor-light-theme.json, next to a dark variant in bdoctor-dark-theme.json.

To make your own, open the Fluent UI Theme Designer, choose a primary, text and background colour, and export the theme from the JSON tab. Save it as a .json file. The export also carries neutralSecondaryAlt, which the register command accepts.

Keep the colours readable. The designer’s accessibility checker shows the contrast of each pair; aim for at least 4.5:1 against white for:

  • themePrimary, as it is link text and white text sits on it on buttons. Many brand colours are too light for this: the Better Doctor teal #24BAA4 reaches only 2.4:1, which is why the light theme uses the darker #117466 (5.7:1).
  • neutralPrimary and neutralSecondary, the body and secondary text.

Leave some margin above 4.5:1 rather than stopping just past it. Links also sit on lightly tinted surfaces: the Better Doctor Markdown web part puts table headers and inline code on neutralLighterAlt in a normal section, and on themeLighter in a section with the Soft background. A themePrimary that only just clears 4.5:1 on white drops below it there; #158274, the colour this theme used before, reaches 4.7:1 on white but 4.4:1 on neutralLighterAlt. The Neutral and Soft sections already move links one shade darker, to themeDarkAlt, so check that shade against themeLighter as well.

In a dark theme the roles swap: white is the page background, black the text colour with the most contrast, and themeLighterAlt the darkest shade of the accent. Choosing a dark background colour in the Theme Designer produces a palette laid out this way. The file does not say that it is dark; the --isInverted flag does, when you register it. m365 spo theme set sets the flag from the command line only, so an isInverted value in the file changes nothing.

Registering a dark palette without --isInverted leaves SharePoint deriving its remaining colours for a light page: error messages, for example, keep the light theme’s dark red, which is hard to read on a dark background. Some of Microsoft’s own example themes set "isInverted": true on a light palette; do not copy that value.

SharePoint also takes a newer theme format, themeSchemaVersion 2.0.0, that adds up to 16 accent and background colour pairs for sections and web parts. m365 spo theme set registers only the palette and the isInverted flag, so a theme in this format has to be registered another way, such as Add-SPOTheme in the SharePoint Online Management Shell. bdoctor applies it by name like any other tenant theme.

Themes belong to the tenant, so each one is registered once and every site can use it. Registering needs the SharePoint Administrator or Global Administrator role. Sign in to the CLI for Microsoft 365 as yourself and register each palette under the name that siteDesign.theme will use:

Terminal window
m365 login
m365 spo theme set --name bdoctor-light --theme '@./bdoctor-light-theme.json'
m365 spo theme set --name bdoctor-dark --theme '@./bdoctor-dark-theme.json' --isInverted

The @ makes the CLI read the file. Keep it in quotes: PowerShell does not accept a bare @ there.

  • Running the same command again updates a theme that already exists.
  • m365 spo theme list lists the registered themes, and m365 spo theme get --name bdoctor-light shows one.
  • m365 spo theme remove --name bdoctor-light removes one.

Add-SPOTheme in the SharePoint Online Management Shell does the same job. A registered theme also appears under Settings > Change the look, so site owners can pick it by hand.

Set the name in bdoctor.json:

{
"siteDesign": {
"theme": "bdoctor-light"
}
}

Then publish with --applyTheme. A custom theme is applied through the tenant admin site: an app registration with Sites.FullControl.All reaches it, and one with Sites.Selected needs the admin app registration.

Publishing pages never changes the site theme, so a site only needs the theme applied once, and again when you switch it to another theme or update the theme’s colours. Pass --applyTheme on the runs that should apply it rather than setting applyTheme in bdoctor.json, which applies the theme again on every publish.