How customizations work
Branding configuration (React UI)
Starting with version 12.9.1, the React UI uses a JSON-based branding configuration system that is fundamentally different from the file-override mechanism used by the legacy and Angular skins.
How it works
The React UI reads its branding configuration from a single file: ui/v2/assets/branding/branding.json. This file contains:
Logo references — file paths for each logo variant (primary-light, primary-dark, logomark-light, logomark-dark), grouped by theme mode
Theme colors — primary and secondary brand colors for light and dark themes, in MUI-compatible palette format
Metadata — version hash for cache busting, company name
When the React application starts, it fetches branding.json and applies the configuration before rendering any UI. This prevents the default Bravura Security branding from flashing before custom branding loads.
Comparison with legacy customization
Aspect | Legacy / Angular (Skins) | React UI (Branding) |
|---|---|---|
Configuration method | SCSS file overrides in | JSON configuration via admin interface or REST API |
Rebuild required | Yes - make.bat must be run | No - changes take effect immediately |
Logo format | SCSS variable referencing image file | Direct file upload with hash-based naming |
Color changes | Edit SCSS variables, rebuild skins | Set via admin UI or PATCH API, instant effect |
Technical skill required | SCSS/CSS knowledge | None (UI-based) or REST API knowledge |
File locations
design/custom/branding/branding.json— The persistent, authoritative branding configuration. Survives skin rebuilds and is replicated across nodes.design/custom/branding/— Persistent storage for uploaded logo files.ui/v2/assets/branding/branding.json— Runtime copy read by the React UI at startup.ui/v2/assets/branding/— Runtime copies of logo files served to browsers.
Fallback behavior
If branding.json is missing or contains invalid data, the React UI falls back to embedded default Bravura Security logos and theme colors. The Zod schema validation logs clear console errors when the configuration is malformed, aiding troubleshooting.
For logo loading, if a referenced logo file returns a 404, the system uses preloaded fallback logos embedded in the React bundle.
Propagating to legacy UI
The React branding system is independent of the legacy skin build. However, to maintain visual consistency across both interfaces, branding changes should also be deployed to the legacy Angular UI by triggering a skin rebuild. This can be done from the branding admin interface or via the REST API rebuild endpoint.
For details on managing branding through the admin interface, see Customizing branding via the admin interface.
Skins
The files that you create in the custom\ directory correspond to the built-in files in the src\ directory. When you generate a skin, the make.bat script looks for a custom file with the same name as the source file. If the custom file exists, then it applies your customizations. For example, the Legacy skin file src\z\psf.m4 contains the tags sinclude(custom/psf.m4) and sinclude(custom/_SKIN/psf.m4) that tell make.bat to apply the code contained in either custom\psf.m4 or custom\default\psf.m4.
Legacy customizations
Legacy skin-specific changes override the built-in and global files in the following way:
The following built-in files are taken, then any global changes are applied, then any skin-specific changes are applied, overwriting only those tags that were customized. The entire file need not be customized, just individual tags:
src\common\*.m4 (except header*.m4 and footer*.m4)
src\common\*.kvg
src\z\*.m4
The following built-in files are replaced by any global file matching its name, which is replaced by any skin specific file matching its name:
src\common\header*.m4
src\common\footer*.m4
src\js\*.js
There are instructions inside these files on how to customize them. All customizations for Legacy JavaScript related files (found in src\js\) must be in a js directory in the same location relative to the source files; for example, if the source file is \<instance>\design\src\js\libs\core.js, then the path for the JavaScript customization must be \<instance>\design\custom\js\libs\core.js.
For more information on skin customizations, see Customizing skins .
Angular customizations
To customize the Angular skins, override files in \<instance>\design\src\ui. For each file, create a new file with the same name in the same relative path in \<instance>\design\custom\, which will override the file of the same name in the same relative location in \<instance>\design\src\ui\.
Style customizations
The following built-in file is replaced by a global file matching its name:
src\ui\src\styles.scss
There are instructions inside of this file on how to customize it.
The following built-in files are appended with the contents of a global file with a matching name pattern (basename-custom.scss) where basename is the portion of the filename before the extension:
src\ui\src\styles.scss
src\ui\src\styles\_common.scss
There are instructions inside of these files on how to customize them.
For more information on style customizations, see Modifying style .
Note
The file-override mechanism described above applies to the legacy and Angular portions of the UI. Starting with version 12.9.1, the React UI uses a different approach for logo and color branding based on a JSON configuration file (branding.json) managed through the admin interface or REST API. See Branding configuration (React UI) for details.
Widgets
The files that you create in the custom\widget\ directory correspond to the built-in files in skin\widget\ directory. When a page is loaded the CGI searches for a custom file with the same name as the source file. If the custom file exists, then your customizations are applied to the page. There is no need to run make.bat for custom widgets.
Widgets are only used in m4 files. For more information on customizing widgets, see Customizing widgets .