theme.json colour presets, and why a pattern should never state a hex
How WordPress turns a palette in theme.json into CSS custom properties, what breaks when a pattern hardcodes a colour, and the fallback chain that fixes it.
WordPress turns palette arrays in theme.json into CSS custom properties on the root element. When block patterns reference those palette slugs, pasted sections inherit active brand colours immediately. When patterns write raw hex values into block attributes, they inject inline styles that bypass the theme's design system entirely.
Understanding how WordPress compiles palette definitions, and why hardcoded hex values create long-term maintenance liabilities, is essential for building durable block themes and authoring portable patterns.
How WordPress compiles palette presets#
A colour palette declared in theme.json defines named slugs and hex values:
{
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "primary", "color": "#1f3a93", "name": "Primary" },
{ "slug": "base", "color": "#ffffff", "name": "Base" },
{ "slug": "contrast", "color": "#111111", "name": "Contrast" },
{ "slug": "secondary", "color": "#e2e8f0", "name": "Secondary" }
]
}
}
}
On render, WordPress generates CSS custom properties on the :root element:
:root {
--wp--preset--color--primary: #1f3a93;
--wp--preset--color--base: #ffffff;
--wp--preset--color--contrast: #111111;
--wp--preset--color--secondary: #e2e8f0;
}
WordPress also generates utility classes: .has-primary-color, .has-primary-background-color, and equivalents for each registered slug.
When you select a palette colour in the block inspector, WordPress saves the slug attribute to the block comment (for example, "backgroundColor":"primary"). The browser resolves the CSS custom property at runtime. If you update #1f3a93 to #0f766e in theme.json, every block referencing primary updates across the site without touching a single database record.
How third-party patterns break theme palettes#
External block patterns commonly introduce colour debt in three distinct ways:
1. Hardcoded inline styles#
Many pattern exporters serialise explicit hex values into the block style object:
<!-- wp:group {"style":{"color":{"background":"#0f1430","text":"#ffffff"}}} -->
Inline styles override utility classes and theme custom properties on that specific element. If your site uses an olive and cream palette, a pasted section with hardcoded navy retains its navy background until manually edited in the code editor. When your client rebrands next year, every hardcoded section requires manual intervention.
2. Missing theme tokens#
Patterns configured against specific themes often reference non-standard slugs like accent-3 or tertiary. In a theme that only declares primary, base, and contrast, the generated CSS becomes:
color: var(--wp--preset--color--accent-3);
Because --wp--preset--color--accent-3 is undefined, the browser falls back to the inherited text colour. In dark sections with light text, this frequently leads to dark text rendering over dark backgrounds, rendering headlines invisible without throwing a validation error.
3. Inconsistent slug naming across themes#
Across default themes like Twenty Twenty-Five and Twenty Twenty-Four, only two slugs are universally present: base (background) and contrast (foreground). Theme developers use divergent names for brand colours (primary, accent, brand, vivid-cyan-blue).
The two architectural solutions: pure inheritance vs scoped design#
Depending on the section's purpose, WordPress developers can handle palette integration in two clean ways:
- Pure Core Patterns (complete theme inheritance): A pattern ships with zero inline hex codes and zero colour classes of its own. It relies entirely on the container's inherited typography and background, allowing the active block theme to set every hue.
- Interactive Patterns with scoped stylesheets: When a layout requires a curated palette or deliberate visual contrast, the styles are supplied via a companion plugin stylesheet. An inspector toggle allows users to choose between Designed (the curated palette) and Use my theme (adapting directly to active
theme.jsontokens).
Here is a live example of an Interactive Pattern demonstrating how a layout can transition between a curated palette and active theme tokens:
Authoring resilient fallback chains#
When custom blocks or bespoke sections must declare colour relationships while remaining portable across unknown third-party themes, use nested var() fallback chains:
color: var(--wp--preset--color--primary,
var(--wp--preset--color--contrast,
#111111));
This fallback cascade resolves in three tiers:
- Target theme token: The preferred brand token (such as
primary). - Standard theme fallback: A universal token defined by virtually all block themes (
contrastorbase). - Static hex fallback: A neutral default ensuring legibility if custom properties fail entirely.
Maintaining accessible contrast across unknown palettes#
Fallback chains prevent undefined CSS, but accessible contrast requires disciplined token selection:
- Anchor body text to base and contrast tokens: Use
contrastfor dark text on light backgrounds andbasefor light text on dark backgrounds. Avoid mapping paragraph text to volatile accent slugs that may resolve to pastels in some themes. - Audit style variations: If your theme provides alternative style variations (
styles/*.json), test your core patterns across each variation to confirm that foreground and background pairings maintain a minimum 4.5:1 contrast ratio. - Avoid low-contrast borders: Input fields and card boundaries must maintain at least 3:1 contrast against surrounding surfaces under WCAG 2.1 Success Criterion 1.4.11.
How style variations affect colour compilation#
In block themes, style variations live in the theme's styles/ directory as individual JSON files (for example, styles/midnight.json or styles/warm-sand.json). A style variation can redefine the active colour palette without changing templates:
{
"version": 3,
"title": "Midnight",
"settings": {
"color": {
"palette": [
{ "slug": "base", "color": "#090d16" },
{ "slug": "contrast", "color": "#f8fafc" },
{ "slug": "primary", "color": "#38bdf8" }
]
}
}
}
When a site administrator selects the "Midnight" variation in the Site Editor, WordPress swaps the CSS custom property definitions on :root. Because the slugs (base, contrast, primary) remain unchanged, every block and pattern referencing those slugs inverts its palette cleanly.
If a pattern relied on an ad-hoc slug that only existed in the default theme, switching to a style variation breaks the fallback cascade. When authoring block themes with multiple style variations, ensure that every variation defines the identical set of palette slugs even as their underlying hex values invert.
Detecting hardcoded colours with WP-CLI#
You can audit your database for patterns and sections that bypassed the theme palette by scanning post_content for raw hex values:
# Identify published posts with inline hex colours in block markup
wp db query "SELECT ID, post_title FROM wp_posts WHERE post_content REGEXP 'style=.*#[0-9a-fA-F]{3,6}' AND post_status = 'publish';"
Reviewing these records will highlight pasted sections from legacy libraries or manual editor overrides that need to be reconnected to theme.json tokens.
Auditing theme colours in the browser#
To check colour declarations on an active site:
- Open DevTools, inspect the
<html>element, and verify the--wp--preset--color--*variables declared under:root. - Search
post_contentin your database for#characters inside block markup to locate hardcoded inline overrides. - Switch between block themes in development to confirm that pasted layouts inherit new palettes cleanly.
Every Pattern Paste Core Pattern is built to inherit active theme design tokens with zero hardcoded colours, while Interactive Patterns provide curated styling with a one-click theme toggle. Browse the catalogue, or explore how block themes load assets on demand.
From the library






