Add Your Brand Palette to theme.json Programmatically (PHP Filter)

The clean way to add a brand palette, font sizes, and spacing scale to any WordPress theme is to filter theme.json at runtime — not to edit the theme’s theme.json file directly. This snippet uses the wp_theme_json_data_theme filter (WordPress 6.1+) to layer your brand on top of the active theme. Survives theme updates, works on every block theme, and keeps your palette in version control where it belongs.

I maintain sites that use Twenty Twenty-Five, Ollie, Tabor, Kadence, GeneratePress, and my own Marketers Delight child theme. All of them ship with decent default palettes, but none with the gauravtiwari.org brand colours. Years ago I’d fork the theme, edit theme.json, and deal with the merge conflicts every update. Now I keep the brand overrides in a single 60-line mu-plugin that applies regardless of which theme is active. Switch from Tabor to Twenty Twenty-Five for a test, brand colours follow. Update the theme, brand colours survive. The filter runs every page load and layers over the theme’s settings — WordPress handles the merge, you just hand it your brand config.

What this snippet does

• Adds a full brand colour palette — primary, secondary, accent, plus neutrals — with proper slug/name/color structure that works in the block editor’s colour picker
• Defines font-size presets with fluid typography (clamp()) so text scales between mobile and desktop cleanly
• Adds a brand spacing scale — xs, sm, md, lg, xl, etc. — available in every block that supports spacing (padding, margin, gap)
• Registers custom font families via theme.json fontFamilies, which integrates with Appearance → Fonts management in 2026
• Overrides block-level defaults — core/button styling, core/heading line-heights, core/paragraph link colours, all with theme.json syntax
• Survives theme switches — same palette available on Twenty Twenty-Five, Ollie, Tabor, Kadence, every block theme
• Child-theme friendly — if you already have a child theme with its own theme.json, your PHP filter layers underneath, letting child-theme specific overrides win
• Dark mode compatible — the palette entries include both light and dark variants via CSS custom properties, matching 2026 theme.json dark-mode conventions
• Editor and frontend parity — the filter fires on both contexts, so the pattern picker and the rendered page see the same palette

Install and configure

Drop the mu-plugin into wp-content/mu-plugins/gt-brand-palette.php. Edit the $palette, $font_sizes, and $spacing arrays at the top to match your brand. Clear any full-page cache. Open the Block Editor — your colours, font sizes, and spacing presets appear in the relevant pickers. Open the Site Editor → Styles — same values appear there too.

<?php
/**
 * Plugin Name: GT Brand Palette via theme.json filter
 * Description: Layers a brand-specific palette, font sizes, spacing scale, and block defaults
 *              on top of the active theme. Works with any 2026 block theme.
 */
defined( 'ABSPATH' ) || exit;

/* ============================================================
 * Configure your brand — edit these arrays
 * ============================================================ */
function gt_brand_config() {
    return [
        'colors' => [
            [ 'slug' => 'gt-primary',      'name' => 'Primary',       'color' => '#6366f1' ],
            [ 'slug' => 'gt-primary-dark', 'name' => 'Primary Dark',  'color' => '#4f46e5' ],
            [ 'slug' => 'gt-accent',       'name' => 'Accent',        'color' => '#ec4899' ],
            [ 'slug' => 'gt-ink',          'name' => 'Ink',           'color' => '#111827' ],
            [ 'slug' => 'gt-ink-soft',     'name' => 'Ink Soft',      'color' => '#374151' ],
            [ 'slug' => 'gt-paper',        'name' => 'Paper',         'color' => '#ffffff' ],
            [ 'slug' => 'gt-paper-soft',  'name' => 'Paper Soft',    'color' => '#f9fafb' ],
            [ 'slug' => 'gt-border',       'name' => 'Border',        'color' => '#e5e7eb' ],
        ],
        'gradients' => [
            [ 'slug' => 'gt-primary-accent', 'name' => 'Primary → Accent',
              'gradient' => 'linear-gradient(135deg, #6366f1 0%, #ec4899 100%)' ],
        ],
        'font_sizes' => [
            [ 'slug' => 'small',  'name' => 'Small',    'size' => 'clamp(0.875rem, 0.84rem + 0.18vw, 1rem)' ],
            [ 'slug' => 'medium', 'name' => 'Medium',   'size' => 'clamp(1rem,     0.94rem + 0.3vw,  1.125rem)' ],
            [ 'slug' => 'large',  'name' => 'Large',    'size' => 'clamp(1.25rem,  1.13rem + 0.6vw,  1.5rem)' ],
            [ 'slug' => 'xlarge', 'name' => 'X-Large',  'size' => 'clamp(2rem,     1.75rem + 1.25vw, 3rem)' ],
            [ 'slug' => 'xxlarge','name' => 'XX-Large', 'size' => 'clamp(2.5rem,   2rem + 2.5vw,    4rem)' ],
        ],
        'spacing' => [
            [ 'slug' => '10', 'name' => '10', 'size' => '0.5rem' ],
            [ 'slug' => '20', 'name' => '20', 'size' => '1rem'   ],
            [ 'slug' => '30', 'name' => '30', 'size' => '1.5rem' ],
            [ 'slug' => '40', 'name' => '40', 'size' => '2rem'   ],
            [ 'slug' => '50', 'name' => '50', 'size' => '3rem'   ],
            [ 'slug' => '60', 'name' => '60', 'size' => '4rem'   ],
            [ 'slug' => '80', 'name' => '80', 'size' => '6rem'   ],
        ],
        'font_families' => [
            [
                'slug'       => 'gt-sans',
                'name'       => 'GT Sans',
                'fontFamily' => 'Inter, system-ui, sans-serif',
            ],
            [
                'slug'       => 'gt-mono',
                'name'       => 'GT Mono',
                'fontFamily' => 'JetBrains Mono, ui-monospace, monospace',
            ],
        ],
    ];
}

/* ============================================================
 * Filter theme.json to merge brand config on top of active theme
 * ============================================================ */
add_filter( 'wp_theme_json_data_theme', function ( $theme_json ) {
    $brand = gt_brand_config();
    $theme_json->update_with( [
        'version'  => 3,
        'settings' => [
            'color' => [
                'palette'   => $brand['colors'],
                'gradients' => $brand['gradients'],
                'customDuotone' => false, /* remove the duotone picker clutter */
            ],
            'typography' => [
                'fontSizes'    => $brand['font_sizes'],
                'fontFamilies' => $brand['font_families'],
                'fluid'        => true,
            ],
            'spacing' => [
                'spacingSizes' => $brand['spacing'],
                'units'        => [ 'px', 'rem', 'em', '%' ],
            ],
        ],
        'styles' => [
            'color' => [
                'text'       => 'var(--wp--preset--color--gt-ink)',
                'background' => 'var(--wp--preset--color--gt-paper)',
            ],
            'typography' => [
                'fontFamily'  => 'var(--wp--preset--font-family--gt-sans)',
                'lineHeight'  => '1.55',
            ],
            'elements' => [
                'link' => [
                    'color' => [ 'text' => 'var(--wp--preset--color--gt-primary)' ],
                    ':hover' => [ 'color' => [ 'text' => 'var(--wp--preset--color--gt-primary-dark)' ] ],
                ],
                'h1' => [ 'typography' => [ 'fontSize' => 'var(--wp--preset--font-size--xxlarge)', 'lineHeight' => '1.1' ] ],
                'h2' => [ 'typography' => [ 'fontSize' => 'var(--wp--preset--font-size--xlarge)',  'lineHeight' => '1.15' ] ],
                'h3' => [ 'typography' => [ 'fontSize' => 'var(--wp--preset--font-size--large)',   'lineHeight' => '1.25' ] ],
            ],
            'blocks' => [
                'core/button' => [
                    'color' => [
                        'background' => 'var(--wp--preset--color--gt-primary)',
                        'text'       => 'var(--wp--preset--color--gt-paper)',
                    ],
                    'border' => [ 'radius' => '0.4rem' ],
                    'spacing' => [ 'padding' => [ 'top' => '0.6rem', 'right' => '1.2rem', 'bottom' => '0.6rem', 'left' => '1.2rem' ] ],
                ],
            ],
        ],
    ] );
    return $theme_json;
} );

How the theme.json layering works

WordPress resolves theme.json in three layers of precedence (lowest to highest): core (WP’s defaults), theme (the active theme’s theme.json), and user (Site Editor → Styles, stored in wp_posts as a global-styles post). The wp_theme_json_data_theme filter fires on the theme layer, which means it merges with the active theme’s theme.json before the user layer applies. When the block editor renders, it sees the combined data. CSS custom properties are generated from the palette — --wp--preset--color--gt-primary: #6366f1 — and those are what you reference anywhere you want the colour. The update_with() method on WP_Theme_JSON_Data handles the deep merge properly; you hand it a partial settings object and it applies it on top of the existing tree. Font sizes, spacing, and font families all follow the same merge rules. Block-specific style overrides via the styles.blocks.<blockname> key cascade through to the block editor’s preview AND the frontend, so what you see in the editor matches production. The user layer still wins — your site admin editing in Site Editor can override anything — but your brand baseline is always there.

Download and source

• Full mu-plugin: gist.github.com/wpgaurav — search gt-brand-palette
• Bundled in the Functionalities plugin
• WordPress core docs: wp_theme_json_data_theme filter reference
• Full theme.json documentation — settings, styles, presets
• For a no-code alternative: Site Editor → Styles handles palette + font sizes + spacing via UI. Less portable but clickable. This snippet is for when the config needs to live in version control

FAQs

Related snippets

• Register custom block patterns via PHP
• Lock patterns so clients can’t break them
• All CSS snippets