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:
- Create the palette.
- Register it in the tenant.
- 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.
What a theme changes
Section titled “What a theme changes”A theme is 22 colours plus an isInverted flag that marks a dark theme.
- The accent:
themePrimaryand its shades,themeLighterAlttothemeDarker. SharePoint uses them for links, buttons, selected navigation, and the header and footer backgrounds that thesiteDesign.chromeemphasis settings pick. - The neutrals:
whiteis the page background,neutralPrimarythe body text,neutralSecondarythe 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.
Create the palette
Section titled “Create the palette”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#24BAA4reaches only 2.4:1, which is why the light theme uses the darker#117466(5.7:1).neutralPrimaryandneutralSecondary, 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.
Dark themes
Section titled “Dark themes”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.
The 2.0.0 theme format
Section titled “The 2.0.0 theme format”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.
Register the theme
Section titled “Register the 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:
m365 loginm365 spo theme set --name bdoctor-light --theme '@./bdoctor-light-theme.json'm365 spo theme set --name bdoctor-dark --theme '@./bdoctor-dark-theme.json' --isInvertedThe @ 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 listlists the registered themes, andm365 spo theme get --name bdoctor-lightshows one.m365 spo theme remove --name bdoctor-lightremoves 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.
Apply it to the site
Section titled “Apply it to the site”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.