Design tokens are the CSS custom properties that power all visual styling in wpTruss. Every colour, spacing value, font size, shadow, radius, and typography setting across all blocks is expressed as a token, a CSS custom property injected into :root on every page and inside the Gutenberg editor iframe.
When a site owner changes their brand primary colour in wpTruss Brand Settings, every block that references --wpt-color-primary updates instantly, no recompile, no cache clear, no block code changes required.
There are 141 core tokens across 24 groups. The token cache is busted automatically when brand settings are saved. A manual cache clear via the debug panel forces an immediate refresh.
How to Use Tokens in Block CSS
Always use var() with a fallback. The fallback catches the rare case where tokens are not yet injected, for example, during the first paint before wp_head fires.
.wpt-my-block__heading {
color: var(--wpt-color-text, #1A1A1D);
font-size: var(--wpt-text-3xl, 1.875rem);
font-family: var(--wpt-font-heading, sans-serif);
}
Never hardcode hex values without a corresponding token as the primary value. The block validator flags bare hex colour values in your CSS as token compliance warnings.
Token Naming Prefix Reference
All tokens use one of two prefixes. Understanding which prefix to expect for which kind of value prevents lookup time:
--wpt- is used for brand-configurable values, colours, fonts, spacing, shadows, radius, transitions. These are the tokens site owners can influence through Brand Settings.
--tp- is used for structural and layout constants, container widths, grid columns, z-index scale, layout padding, easing curves. These are architectural constants that do not change per brand. Note that --tp- tokens are still part of the wpTruss system (not a separate prefix), the distinction is conceptual, not a namespace difference.