Theme Tokens

Theme tokens define the site-wide configuration exposed by a theme.

Rather than hardcoding values such as colours, navigation or contact information, themes declare configurable tokens in their manifest.json. Masthead automatically generates an editor for these tokens, allowing site owners to customize the theme without modifying its templates.

Declaring a token

Every token is declared in the tokens section of the theme manifest.

{
  "tokens": [
    {
      "key": "accent",
      "label": "Accent color",
      "type": "color",
      "default": "#0f766e"
    }
  ]
}

Every token has a unique key, a display label and a type. Most token types also support a default value.

Accessing tokens

Tokens are available inside every template through theme.tokens.

<h1 style="color: {{ theme.tokens.accent }}">
  Welcome
</h1>

Scalar values are also exposed as CSS custom properties.

For the example above, Masthead automatically generates:

:root {
  --accent: #0f766e;
}

This allows themes to expose configurable styling without requiring additional JavaScript.

Token types

Masthead supports several different token types.

Type	Description
string	A single line of text.
text	Multi-line text.
number	Numeric value.
length	CSS length values such as 16px or 2rem.
color	Colour picker.
url	URL input.
boolean	Checkbox.
select	Dropdown list.
file	Uploaded asset.
object	A group of related fields.
list	A repeatable collection of fields.

Simple themes typically use scalar values, while more advanced themes often rely on objects and lists to model structured content.

File tokens

File tokens allow site owners to select an uploaded asset from their site.

{
  "key": "logo",
  "label": "Logo",
  "type": "file"
}

Inside templates, the value is exposed as the public URL of the uploaded file.

<img src="{{ theme.tokens.logo }}" alt="Logo">

If no file has been selected, the value is empty.

File tokens are commonly used for logos, favicons, background images and other site-wide assets.

Organizing tokens

Large themes can organize tokens into categories.

{
  "key": "accent",
  "category": "Branding"
}

Categories are used by Masthead to group related settings in the editor.

They do not affect how tokens are accessed inside templates.

Site-wide configuration

Theme tokens belong to the site rather than an individual page.

This makes them ideal for values that should remain consistent throughout the entire website, such as:

• Colours
• Logos
• Navigation
• Footer links
• Contact information
• Social media links

If a value should be configurable per page instead, use page metadata instead.

Next steps

Simple token types are useful for individual values, but themes often need more structured configuration.

The following guides introduce objects and lists, followed by page metadata, which uses the same declaration format for page-specific configuration.