Migrating Brand Vocabulary

While referencing another table layout, a temporary codename spread into our components, styles, tests and website copy. Compilation cannot catch this: the name is spelled correctly and its references resolve, but it does not belong in our product. Cleanup has to treat source identifiers, customer copy, filenames and accidental bytes in machine data differently; one repository-wide string replacement will not do.

We first fixed the replacement names: customer copy says “New table,” and components, identifiers and related tests use Table2 / table2. Then we migrated along the dependencies: inventory tracked and unignored files with git ls-files --cached --others --exclude-standard -z, rename files and directories and repair imports, routes and test selectors, then update copy, snapshots, screenshot names and generated data. scripts/brand-language-machine-data.mjs rewrites machine data into supported equivalent forms (Unicode escapes in JSON fields, numeric character references in HTML src/href data URIs), so the source bytes change while the parsed values stay the same; the technique does not apply to ordinary prose.

scripts/brand-language-guard.mjs then checks filenames and contents in pre-push and CI. Its binary exceptions are explicit: valid ZIP-format APKs skip their contents but keep filename checks; supported PNGs that pass structural validation skip compressed pixel data but still scan other bytes and text metadata; unsupported or invalid PNGs get a full byte scan. It therefore does not promise zero matches across every binary’s raw bytes. Git history, ignored files and external caches are outside the scan, and a name check cannot prove original visual design or replace trademark review.

The lesson: settle the names first, then migrate every consumer, and when a name changes again, move the references and the guard together.