Changing a Theme You Did Not Write

The request is small. Make the footer say the client's slogan, change the accent colour, and keep the rest of the design. It is the kind of job that used to be a five-minute functions.php edit, and it is the kind of job where an agent will confidently edit the wrong file, because the wrong file is usually the first one it finds.

There are only three places a theme change can live, and choosing between them is the whole skill. Code you added lives in a child theme. Data the site owner should control lives in the database. Behaviour that must survive a theme switch lives in a plugin. Every bad outcome in this lesson comes from putting a change in the wrong one, and the failure is usually invisible until an update lands six weeks later.

A child theme is an override, and overrides only work in one direction

A child theme does not modify its parent. It supplies files with the same names, and WordPress's template hierarchy checks the child directory first. The parent's copy of that file is still on disk, untouched, and the next parent update replaces it without affecting yours. That is the entire mechanism, and it is why the first rule is to confirm you are editing the child.

wp theme list --status=active
wp eval 'echo get_stylesheet(), " / parent: ", get_template(), "\n";'

$ wp eval 'echo get_stylesheet(), " / parent: ", get_template(), "\n";'
acme-studio / parent: twentytwentyfive

get_stylesheet() is the active theme, and it is the directory your edits belong in. get_template() is the parent, and it is the directory that gets overwritten. When those two differ, the ratio of "safe to edit" to "will be lost" is exactly one to one across the whole theme, and nothing about a filename tells you which one you opened.

The trap for agent work is that the parent theme is often the more interesting directory. It contains every template, every pattern and every style the design actually uses, so an agent asked to "change the header" will search the parent, find templates/page.html, and rewrite it there. The change works immediately. It works for weeks. Then Twenty Twenty-Five updates and the change is gone, and the diff you review will not be the one that caused it.

theme.json is a merge, and the merge has three layers

Block themes put design tokens in theme.json rather than in PHP, and the resolver merges three layers in a fixed order: WordPress's own defaults, the theme file, then the user's saved global styles from the site editor. Later layers win. A colour you add to the theme file can therefore be present in the file, present in the editor, and absent from the page.

The cheap way to see the merged result is to ask WordPress for it instead of reading the file.

wp eval '
$settings = wp_get_global_settings();
foreach ( $settings["color"]["palette"]["theme"] as $entry ) {
	printf( "%s = %s\n", $entry["slug"], $entry["color"] );
}'

Run on a child theme whose theme.json declares exactly one colour, that command printed one line:

brand = #0b5fff

One line is the surprising result. The parent theme's theme.json declares eight palette colours, and none of them survived. When both a child and a parent ship a theme.json, the child's file is the theme layer and the parent's presets are not merged into it. Add one colour to the child and you have replaced the palette, which is the difference between a change that adds a brand colour and a change that removes seven.

The rendered page is the third opinion, and it is the one that counts. On that same install, the HTML contained --wp--preset--color--brand and nothing for the parent's accent-1 through accent-3, while core's own presets such as black and white were still present. Three layers, three answers, and only the last one is what the client sees.

Editing a parent template is sometimes right, and never by accident

There is a legitimate version of the parent-theme edit: you copy the parent file into the child, keep the path, and edit the copy. WordPress loads the child's file because the hierarchy reaches the child directory first, and the parent stays pristine for the next update. The mechanical part is easy and the judgement is not, because you have just forked a file that the parent will continue to improve.

Three questions decide whether to fork a template at all. Does the change belong in markup, in which case a template override is honest, or in styling, in which case it belongs in CSS or theme.json and the template should stay untouched? Will the parent change this file in a way you need? And can the same result be produced by a filter, which costs no fork at all? A footer slogan, for example, is usually an option read by a small function in the child theme, not a copy of a 200-line template.

When you do fork, commit the fork on its own, before you edit it, and write down the parent version you copied from. The commit is what lets the next person answer the only question that matters two years later: has the parent file changed since we took this copy?

Prove the change reached the page before you call it done

A theme edit is finished when the page contains the change. Not when the editor previews it, not when the agent reports that the file was updated, and not when the child theme directory contains the string you asked for. You can check all three of those while the visitor sees the old value, because WordPress caches the theme layer and servers cache the response.

curl -s "https://acme.test/" | grep -c "acme-swatch"
curl -s "https://acme.test/" | grep -o -- "--wp--preset--color--brand"
grep -rn "acme_studio_footer_note" wp-content/themes/

The third command is the one that catches the expensive mistake, because it shows every directory the string appears in. If it only appears under the parent theme, the change is on borrowed time. If it appears in both, someone edited both copies and you now have two sources of truth.

<?php
// Child theme: add to the parent palette instead of replacing it.
add_filter( 'wp_theme_json_data_theme', 'acme_studio_add_brand_colour' );

function acme_studio_add_brand_colour( $theme_json ) {
	$data = $theme_json->get_data();

	$data['settings']['color']['palette'][] = array(
		'slug'  => 'acme-blue',
		'color' => '#0b5fff',
		'name'  => 'Acme Blue',
	);

	return $theme_json->update_with( $data );
}

$ wp eval '$s = wp_get_global_settings(); foreach ( $s["color"]["palette"]["theme"] as $e ) { printf( "%s = %s\n", $e["slug"], $e["color"] ); }'
acme-blue = #0b5fff