Design Token Reference: Custom Tokens

Custom tokens extend the 141 core tokens with values you define. They are injected after core tokens in the same :root block and are available in all block CSS files.

Creating Custom Tokens

Custom tokens are defined in Brand Settings → Custom Tokens. The token name you enter is automatically prefixed with --wpt-custom- and injected into :root. Custom token names must not collide with any core token, the settings UI enforces this with a conflict check at save time.

Example: If you define a custom token named brand-gold with value #C9A84C, it becomes available as --wpt-custom-brand-gold in all block CSS files.

Using Custom Tokens in Block CSS

.wpt-my-block__badge {
    background: var(--wpt-custom-brand-gold, #C9A84C);
    color: var(--wpt-color-dark);
}

Using Custom Tokens in Element Definitions

This is where custom tokens become especially powerful. If you add --wpt-custom-brand-gold to your brand, you can expose it as an option in any element definition file:

// src/elements/heading.js — add to color options
{ label: 'Brand Gold', value: 'custom-brand-gold' },

And in your block’s style.css, map that class modifier to the token:

.wpt-heading--color-custom-brand-gold {
    color: var(--wpt-custom-brand-gold);
}

Now site owners can select “Brand Gold” as a heading colour across every block that uses the heading element, all from a single place.

Custom tokens appear on window.wptTokens.custom in the editor for JavaScript access.