Data Machine has two theming surfaces because it renders in two different runtimes:

Use CSS custom properties when the browser paints the UI. Use BrandTokens when PHP renders pixels before the browser sees the output.

Pick A Surface

Do not use a PHP filter to style browser UI. Do not use CSS variables as the only source for GD image templates.

CSS Tokens

Browser-rendered interfaces read tokens from inc/Core/Admin/assets/css/root.css.

Core tokens:

Themes and plugins can bridge site tokens into Data Machine tokens:

:root {
    --datamachine-text-primary: var(--wp--preset--color--foreground);
    --datamachine-text-secondary: var(--wp--preset--color--contrast-2);
    --datamachine-bg-light: var(--wp--preset--color--base-2);
    --datamachine-blue: var(--wp--preset--color--primary);
    --datamachine-border-radius: var(--wp--custom--radius--small);
}

Consumers should read the Data Machine token names, not site-specific names. That keeps Data Machine UI portable across themes.

BrandTokens

Server-side image templates read DataMachineAbilitiesMediaBrandTokens.

GD cannot read CSS variables, web fonts, or browser-computed styles. Templates call BrandTokens::get(), BrandTokens::color(), or BrandTokens::font() and receive plain PHP values.

Core token shape:

Example bridge:

use DataMachineAbilitiesMediaBrandTokens;

add_filter(
    'datamachine/image_template/brand_tokens',
    static function ( array $tokens, string $template_id, $context ): array {
        $tokens['colors']['background']   = '#ffffff';
        $tokens['colors']['accent']       = '#0073aa';
        $tokens['colors']['text_primary'] = '#111111';
        $tokens['brand_text']             = get_bloginfo( 'name' );
        $tokens['logo_path']              = get_stylesheet_directory() . '/assets/logo.png';
        $tokens['fonts']['heading']       = get_stylesheet_directory() . '/assets/fonts/Heading.ttf';

        return $tokens;
    },
    10,
    3
);

$accent = BrandTokens::color( 'accent', 'event_og_card' );

Font paths must point to TTF or OTF files. GD cannot render WOFF2 directly.

Alignment Rules

Data Machine keeps the two surfaces logically aligned, not mechanically identical.

• New generic browser tokens should have an equivalent BrandTokens value when server-rendered images need the same concept.
• New BrandTokens values should have an equivalent CSS custom property when browser-rendered UI needs the same concept.
• Consumer plugins should not redefine a generic token that Data Machine already publishes.
• Site-specific values should bridge into Data Machine’s token names instead of replacing the token vocabulary.

If a third theming surface appears, consider moving the shared logical token catalog to a generated source. Until then, parallel explicit surfaces are simpler than build-time indirection.