Multi-Theme Parity

3 views Markdown

A behavioural fix belongs in every theme that carries the same file, and a tool says which themes still lack it.

Overview

An installation ships several themes. They share a file layout and mostly the same markup. A defect found in one theme is rarely a defect of that theme: it belongs to the file, wherever that file was copied.

The rule is short. A fix made in one theme is made in every theme that carries the counterpart of that file. It works both ways, and memory does not keep it: the second theme lints clean on its own.

Prerequisites

  • Two or more themes under templates/website. The tool finds them from the manifest in each directory.
  • A finished change. Run the check after the fix: its input is what you touched.
  • A place to record deliberate differences. An unexplained missing file is a bug.

Structure

Two Triggers, One Tool

SituationDirectionWhat you do
A bug, a behaviour, a security hole or an accessibility defect. Outwards, to every other theme. Apply the same fix to every theme with the counterpart file, then run the single-file check.
You are building a new theme, or adding a page or a component. Inwards, from the other themes. Run the inventory. Port every missing file, or write it down as intentionally absent.

Whether a difference is deliberate depends on the nature of the change.

Kind of changeTravels toWhy
Behaviour, correctness, security, accessibility, data handling Every theme None of this is visual identity. A theme may look different; it may not be less correct.
Colour, spacing, a structure from that theme's own design source Only that theme This is what makes a theme a theme. Copying it outwards erases the other theme's design.

Why the Comparison Is Theme Neutral

Two copies of the same component are never byte-identical, because each theme owns its own prefixes. So each file is normalised first, and only real content differences survive:

  1. Custom property and data attribute prefixes fold together.
  2. The JavaScript namespace folds, so a call through one theme's global object equals another's.
  3. The bare theme name folds everywhere, class names included.

A reported difference is a difference in what the file does, not in what it is called.

Walkthrough

1. Run It After Every Fix

  1. Fix the file in the theme you were working in.
  2. Run the single-file check on the path you touched.
  3. If the round touched several files, use the changed-files mode.
after a fix 
php .claude/tools/theme-parity.php views/account/services.tpl   # one file
php .claude/tools/theme-parity.php --changed                    # everything this round touched

2. Read the Verdict

Three outcomes; only one means you are finished.

OutputMeaningWhat to do
All equivalent Same content everywhere, once prefixes are folded. Nothing. The fix travelled.
Diverging, with theme names and a character delta The named themes hold a different version. Deliberate visual identity stays. Anything else has not reached those themes yet.
Missing, with theme names The file does not exist in those themes. Port it, or write down why it is absent.

3. Close the Gap

  1. Port the file, or record the substitution.
  2. Verify by counting, not by loading.
  3. Count the marker it should have produced: a styled class, a preset wrapper, a layout shell.
Missing pieceWhat the page doesHow to catch it
A table preset Loads. The component falls back to raw columns. Count the preset's classes in the output; zero means it never loaded.
A stylesheet rule Loads. The class matches nothing, so the block appears unstyled. Compare the count of the styled class across themes.
A block override Loads, inside the wrong shell. Check what surrounds the content, not the content.

Reference

Invocation

No argument Inventory. Every theme with its file count, then every file missing from at least one theme. A new theme is finished against this mode.
A file path Single file. Prints who has it, who does not, and whether the copies are equivalent.
The changed-files switch Every theme file changed in the working tree, with a count of how many need attention.

What Is Compared

Included Templates, PHP, JavaScript and stylesheets under the theme root. A fix inside a stylesheet is the kind that gets left behind.
Excluded: the saved settings file Each installation writes its own operator-chosen values there, so comparing it would be noise.
Excluded: vendored libraries Third-party code is expected to be byte-identical.
How themes are discovered Every directory under the website templates root that holds a theme manifest.

Exit Codes

Usable as a gate, not only as a report.

exit status 
0   nothing needs attention: present everywhere and equivalent everywhere
1   at least one file is missing somewhere, or one copy has diverged
    (in the inventory mode, 1 simply means the tree still has unexplained gaps)

# Fewer than two themes is not a failure, it is a no-op: the tool says so and exits 0.
php .claude/tools/theme-parity.php views/account/services.tpl; echo "exit: $?"

Example

Real output, one block per verdict.

the fix travelled 
$ php .claude/tools/theme-parity.php components/news-newsletter.tpl

=== components/news-newsletter.tpl
   var    : Basic, WCOM, WStyle
   ✔ içerik: hepsi eşdeğer (tema-nötr karşılaştırma)
one theme diverged 
$ php .claude/tools/theme-parity.php views/account/services.tpl

=== views/account/services.tpl
   var    : Basic, WCOM, WStyle
   ⚠ içerik: Basic ile AYRIŞAN → WCOM
      WCOM       124 karakter fark

All three themes have the file; one holds a version 124 characters apart. A layout decision stays. Your fix has not arrived yet.

the file exists in one theme only 
$ php .claude/tools/theme-parity.php partials/client-subnav.tpl

=== partials/client-subnav.tpl
   var    : Basic
   ❌ YOK  : WCOM, WStyle  <-- ya taşı ya da tema-özel/ikame olarak belgele

This gap is legitimate only because it is written down: the other two themes navigate with a sidebar instead.

the inventory, for finishing a theme 
$ php .claude/tools/theme-parity.php

Tema (3): Basic, WCOM, WStyle
   Basic      229 dosya
   WCOM       514 dosya
   WStyle     249 dosya

Tüm temalarda olan: 218 dosya
Bazılarında eksik : 321 dosya

--- eksik olanlar (dosya → hangi temalarda YOK) ---
  assets/css/app-detail.css                            YOK: Basic, WStyle
  ...
  assets/css/client-nav.css                            YOK: Basic, WCOM
  ...
  assets/css/marketplace.css                           YOK: Basic, WStyle
  ...

Read the list for answers, not for a verdict: a large gap count is not alarming on its own. What matters is that every line has an answer.

Pitfalls

A page that loads is not evidence

All three silent classes answer with a working page, so route tests and a quick look pass. Count the marker the missing piece should have produced.

Copying the source theme when the design was redrawn

First compare the two design sources. Same structure: copy and rename prefixes. Redrawn structure: fidelity to the source is the failure.

Prefixes copied with the markup break silently

Copied markup brings the source theme's prefix along, and the selector then matches nothing. After any port, search the copied files for the source theme's name.

An unexplained gap becomes permanent

The inventory prints missing files, not reasons. A gap nobody wrote down looks like an oversight, and an unread gate is the same as no gate.

The rule does not depend on how many themes exist

It reads the same with two themes as with ten.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket

We use cookies to keep you signed in, remember your language and currency, and improve the site. Cookie Policy