Themes

On this page

A theme is a name, one color for each of 6 roles, and the version of your logo that belongs with it. Most manuals describe two, Light and Dark. Each theme is drawn in its own colors, so a dark theme looks dark even on a light page.

What the block holds

Themes sits in the Layout and surfaces group of the block picker: Light, dark and any other theme, with the colors and logo version each one uses. Add as many themes as you need. Each one holds four things.

Name

Light, Dark or a name of your own.

Roles

One color for each of the 6 roles below.

Logo version

Which version of your logo this theme uses. Optional.

Notes

One line saying where the theme applies. Optional.

The roles are a fixed list. You cannot add or rename one, so every theme answers the same 6 questions.

Adding a theme

WhereDashboard, Brand manual, Content, a section, Add a block, Layout and surfaces, Themes

Add the block to a section, then press Add a theme.
Pick the name. The Theme dropdown offers Light, Dark and Custom. Custom opens a Name field for something like High contrast.
Fill in the colors. Each field takes a hex value, and the swatches under it are your own palette colors, one click each.
Choose the logo version, if you have one.
Write a line under Notes (optional), if the theme needs one.

The first theme you add is named Light for you, and the next one Dark unless a dark theme already exists. Themes can be dragged into another order and duplicated. Duplicating is the quick way to build a dark theme: copy the light one and change the 6 values.

Editing the block needs the permission Edit sections and content. Of the built-in roles, Owner, Admin, Editor have it. See Roles and Custom roles.

The 6 roles

Role	What it paints	If you leave it empty
Background	The ground of the card.	#ffffff, or #111111 in a dark theme
Surface	The panel inside the ground: a sheet, a card, a sidebar.	#f5f5f5, or #1c1c24 in a dark theme
Text	The headline and the main readable text.	black or white, whichever reads on the background
Text muted	Captions, hints, secondary text.	the same color as Text
Primary	The filled button.	#3b3ea8
Border	The edge of the ground and the edge of the surface.	#d6cfc2, or #3a3a46 in a dark theme

A fallback only keeps an unfinished theme looking sensible. It is not exported, and the swatch list beside the preview shows only the colors you actually filled in.

Dark is read from the name

A theme whose name contains dark, night or black, in any case, uses the dark fallbacks. A theme that states all 6 colors never uses a fallback at all.

What counts as a color

Each role takes a hex value with the #: three digits or six, such as #fff or #1a1a1a. Anything else stays in the field but draws nothing on the published page. Short values are filled out in the export, so #fff is exported as #ffffff.

The swatches under each field are the colors your manual already defines in its Color blocks, so most themes are assembled from the palette rather than typed by hand. See Color, contrast, tints and shades.

The logo version

If your manual has a Logo block with variants, the theme offers a Logo version dropdown listing them by label, plus None. Picking one copies the label and the picture into the theme as they are right now. If you rename that variant later in the Logo block, the theme keeps the old name until you pick it again.

If there is no Logo block, the field is Logo for this theme (optional) and takes a picture of its own from your files.

What a reader sees

Each theme is shown twice. On the left, a card painted in the theme colors: the logo on the background, a surface panel holding a line of text, a line of muted text and a filled button. On the right, each color you filled in as a swatch with its name and hex value. The note, if there is one, sits under the card.

A theme with only a name is not shown

A theme is skipped on the published page unless it has at least one color, a logo or a note. A block in which every theme is like that counts as empty in the completeness check.

Color mode is a different setting

WhereDashboard, Brand manual, Settings, Design, Color mode

Color mode chooses whether your published brand hub is Light or Dark. It is one setting for the whole manual and readers cannot switch it. It has nothing to do with the themes inside the block: a light manual can document a dark theme, and the other way round. See Accent color, header image, dark mode and density.

In the token export

Themes are one of the groups in the token export. Three rules apply.

Only a valid hex is exported. Anything else is left out.
A theme with no color in it exports nothing.
Each theme gets a short name made from its own. Two themes both called Dark export as dark and dark-2. An unnamed theme becomes Theme 1, Theme 2 and so on. Role names are shortened the same way, so Text muted becomes text-muted.

Themes are in the CSS, SCSS, Less, JSON, W3C Tokens, Style Dictionary, Tailwind and JS and TS files. They are not in the SwiftUI, Compose, Flutter, Android XML or CSV files, nor in the Adobe swatch file. Here is what one theme looks like in CSS.

CSS

[data-theme="dark"] {
  --theme-background: #101014;
  --theme-surface: #1c1c24;
  --theme-text: #f5f5f5;
  --theme-text-muted: #a1a1ad;
  --theme-primary: #6366f1;
  --theme-border: #3a3a46;
}

Taking the themes and nothing else

Download all formats (.zip) on the export page (opens in a new tab) has a by-block folder inside it, with one folder per block. The themes folder holds only the themes, as CSS, JSON, W3C Tokens and Tailwind.

The export page also lists each theme on its own, as Theme: Dark with the count of roles and every hex value, so you can check them without downloading anything. Developers can read the same values over the API (opens in a new tab).

Plans

The block is on every plan, including Free, and so is the token export in every format. Nothing about themes is gated. See What each plan includes.

PreviousColor, contrast, tints and shades NextPublishing and unpublishing

Still stuck? Write to hello@stylehub.cloud and say which page you were on.