Why SuiteCRM upgrades undo custom colours, and how to make a theme upgrade-safe

Why does a SuiteCRM upgrade remove custom colours?

A SuiteCRM upgrade replaces the stock files, so colours changed by editing a stock stylesheet are lost. SuiteCRM 8's upgrader also deletes anything added under public/legacy/themes/ and public/dist/. Keep theme work in your own files instead: a separately named sub-theme under custom/, and on SuiteCRM 8 a stylesheet loaded from extensions/.

Why the colours disappear

The fastest way to recolour SuiteCRM is to open the stock stylesheet and change some values. It works until the next upgrade, which ships fresh copies of those same stock files and writes them over yours. Nothing warns you: the upgrade succeeds and the CRM is simply back to Dawn.

The fix is not to avoid upgrades. It is to keep your changes in files the upgrade does not own.

What a SuiteCRM 8 upgrade keeps and replaces

"Mirrored with delete" is stronger than overwritten. A sub-theme folder you added under public/legacy/themes/suite8/css/ is deleted too, because it is not in the new release. The same layout that is fine on SuiteCRM 7 does not survive SuiteCRM 8.

One more SuiteCRM 8 trap: do not leave a style.scss beside your compiled style.css under custom/themes/. SuiteCRM 8's theme build deletes the CSS of any such folder and recompiles it with a tool that production installs do not have, leaving an empty stylesheet. See changing SuiteCRM 8 colours for the full picture.

SuiteCRM 7

SuiteCRM 7 upgrade packages replace the stock theme files, including the four stock sub-themes in themes/SuiteP/css/. Edits made inside Dawn/, Day/, Dusk/ or Night/ are lost. A sub-theme with its own name is not part of the stock file set, and its registration lives in custom/themes/SuiteP/themedef.php, under custom/, where SuiteCRM expects site changes to live.

We tested that on a real upgrade: a separately named sub-theme installed on SuiteCRM 7.14.6, then SuiteCRM's official 7.14 to 7.15.2 upgrade package. Every file in the sub-theme's folder, its registration and the site default in config_override.php were identical afterwards, while the stock Dawn, Day, Dusk and Night stylesheets were replaced with the 7.15.2 versions. After the upgrade SuiteCRM still served the custom sub-theme to signed-in users.

Even so, check your theme after every upgrade. The stock SCSS a sub-theme builds on can change between releases, which is why the safest packages are rebuilt for each SuiteCRM version rather than reused.

An upgrade checklist for a custom theme

1. Before upgrading, note the exact version you are moving to ($suitecrm_version after the upgrade).
2. Confirm none of your theme changes live in stock folders (themes/SuiteP/css/Dawn and friends on 7, public/legacy/themes or public/dist on 8).
3. Upgrade on a staging copy first and open a list view, a record, an edit form and Admin.
4. If your theme came as a version-locked package, download the build for the new version and install it.
5. Run Quick Repair and Rebuild, and on SuiteCRM 8 php bin/console cache:clear, then hard-refresh the browser.

How Brandtint handles upgrades

Brandtint packages install only into folders the upgrader keeps: public/legacy/custom/ and extensions/ on SuiteCRM 8. Each package is built for one SuiteCRM minor version and refuses to install on another, so an old ZIP can never half-apply to a new release. When you upgrade, you open your saved project and download the rebuild for the new version, at no extra cost while your purchase is covered. See pricing for the coverage period.