For theme authors

Themes can hand design values over to Image Socialiser in code. Declared values beat the site settings, and the matching controls on the settings screen render disabled. Users always see that and what the theme controls, and their own stored settings survive untouched: deactivate the theme (or remove keys), and the user's values apply again.

Declaring support

add_action( 'after_setup_theme', function() {
	add_theme_support( 'image-socialiser', [
		'colors' => [
			'background_from' => '#102a43',
			'background_to' => '#243b53',
			'text' => '#f0f4f8',
			'muted' => '#829ab1',
		],
		'fonts' => [
			'heading' => 'inter-bold',   // any registered font id
			'body' => 'inter-regular',
		],
		'font_sizes' => [
			'title' => [ 'min' => 44, 'max' => 80 ],
			'site_name' => 26,
		],
		'layout' => [
			'logo_position' => 'bottom-left',   // four corners
			'show_site_name' => true,
			'text_align' => 'left',             // left | center | right
		],
		'background_image' => get_theme_file_path( 'assets/og-background.png' ),
		'template' => 'split',                  // site-wide default template
		'logo' => 123,                          // attachment ID, or 'none'
	] );
} );

Everything is optional. Only declared keys are taken over; every undeclared key stays user-configurable. Declaring colors.text alone locks exactly one color field.

Key reference

Key	Values	Notes
colors.background_from / colors.background_to	hex color	Gradient stops (Poster uses only background_from as its solid color).
colors.text / colors.muted	hex color	Title color / muted color (the default for the secondary line and site name).
colors.subtitle / colors.site_name	hex color	Individual secondary-line / site-name colors (since 0.19.0); unset values inherit the muted color.
fonts.heading / fonts.body	registered font id	Invalid ids are ignored (site value applies).
font_sizes.title	[ 'min' => int, 'max' => int ]	Auto-fit range for the title, all templates.
font_sizes.site_name	int	Site name size, all templates.
layout.*	same values as the settings	show_site_name, show_logo (bool); site_name_position, logo_position (top-left, top-right, bottom-left, bottom-right); text_align (left, center, right). Templates that pin a token by design (e.g. Poster centers) still win.
background_image	file path or attachment ID	Paths are typically theme assets via get_theme_file_path(). A changed file (theme update) regenerates all images automatically — the content hash includes the file's modification time.
template	template id	Site-wide default (any built-in or registered id). Per-post-type, taxonomy, and special-page choices still override it.
logo	attachment ID or 'none'	'none' suppresses the logo entirely.

Values vs. assets

The theme-support array carries values. Assets are registered through filters:

Custom fonts (TTF/OTF files shipped with the theme):

add_filter( 'image_socialiser_fonts', function( array $fonts ): array {
	$fonts['my-theme-serif'] = get_theme_file_path( 'assets/fonts/serif.ttf' );

	return $fonts;
} );

add_filter( 'image_socialiser_font_urls', function( array $urls ): array {
	$urls['my-theme-serif'] = get_theme_file_uri( 'assets/fonts/serif.ttf' );

	return $urls;
} );

The URL variant feeds the editor's live preview; register both. The font then works everywhere — in fonts.heading, the settings dropdowns, and all templates.

Whole templates:

add_filter( 'image_socialiser_templates', function( array $templates ): array {
	$templates['my-theme-hero'] = [ /* layer stack, see docs/HOOKS.md */ ];

	return $templates;
} );

Combined with 'template' => 'my-theme-hero', a theme ships and applies its own design in one step.

Invalidation

Nothing to do. The content hash covers the fully resolved design — declared values, font files, the background image's modification time — so any change produces new image URLs automatically. Switching themes schedules a full regeneration in the background.