[Index]
Tip
Use the Action search to navigate Automate
Overview
Themes allow you to configure the complete look and feel of the user interface, including images, logos, colors, fonts, sizing, and positioning. Themes can also manage login and interface header text, with the selected theme applicable to the Login page.
You can create any number of new themes and edit existing themes (with the exception of the theme name). The VOSS Product Suite includes a default theme that serves as a baseline template for customization.
Themes are associated with user roles and are typically linked to specific customers (companies). Theme management can be carried out through two primary methods:
Key theme concepts include:
For detailed procedures on creating and managing themes, see Create a Theme in the Business Admin Portal.
Related topics
Theme commands in the Platform Guide
Manage themes in the Core Feature Guide
Tip
Use the Action search to navigate Automate
Note
On upgrade to release 25.4:
The current default is set to the default in System Global Settings.
A migration script scans existing themes for the Use This Theme to style Login Page flag. For each interface type, if one theme has this flag set, the corresponding default theme setting in System Global Settings is updated - see below. If no flagged theme is found, the VOSS theme is used as the fallback according to current standards.
The legacy Use This Theme to style Login Page checkbox setting is removed after migration, and theme selection for roles remains optional. If theme selection is blank, the role inherits the global default theme.
For light and dark mode:
If the system (browser) setting is set to dark mode prior to upgrade and the default theme was the VOSS theme, the upgrade will enable the dark mode in the new voss_platform default theme shipped as the default theme, which comes with dark mode pre-enabled. The VOSS default dark mode palette is applied initially and existing images are duplicated for both modes.
For custom themes, users can add a dark mode to the migrated themes if required. Your existing theme colors are migrated as-is for light mode. If the system (browser) setting is set to dark mode and no dark mode is set, the theme will retain its current settings (light mode).
Currently, the default VOSS light mode theme is compliant for accessibility.
A few new additional colour palette settings will be available to fine tune their light mode or dark modes. By default, these settings will not be set on custom themes light-mode - users can decide if they wish to fine tune or add them.
Managing themes
There are two ways to manage themes for the Admin Portal:
| Directly within the GUI | Custom branding options can be configured within the GUI |
| From the command line | Theme JSON files and associated images can be downloaded and uploaded as .zip files from the command line. For more information, see Theme commands in the Platform Guide. |
To access theme management functionality in the GUI, go to the Themes page.
The following settings groups are available on the Themes page in the Admin Portal:
For details on the values on the Light Mode and Dark Mode color picker tables, see: Administration GUI Theme Customization Color Reference.
Note
Theme export restrictions
A theme residing at a hierarchy level above that of the current user cannot be exported. Such an export will raise an error.
Default theme settings
Important
Only system-level administrators can set the default login themes.
Lower-level administrators cannot override the system-wide default login theme settings.
The system's default login themes are managed centrally through System Global Settings in Administration Tools, rather than per-theme checkboxes. This provides secure, consistent control at the system level.
When a user logs in for the first time, the system default (in other words, the browser default) mode is selected for the login screen. Subsequent login will adhere to the user mode.
System Global Settings includes a Portal Preferences section with dropdown fields for:
The following defaults are provided:
The dropdown displays themes available from the current hierarchy level and below. Only one theme can be set as default for each interface type at any time.
This theme is automatically applied in the following scenarios:
Upload a theme
A theme can be uploaded at a particular hierarchy using the Upload Theme quick link on the Role Based Access dashboard. In this case, the theme will not display in the list view for administrators at lower levels of the hierarchy.
Note
Self-service theme uploads using this upload tool will not be applied. Use the Choose File button on the Self-service theme input form for self-service theme uploads. Contact VOSS for details on the format and contents of the ZIP file to upload.
Applying a theme to the user interface
When uploading or updating a theme, you can choose the Interface where the theme should apply, either the Admin Portal (default), or to the Self-service interface. If no interface is specified, the default applies.
The default login page themes for Administration and Self-service interfaces are controlled centrally via System Global Settings in Administration Tools. This ensures consistent, system-wide control of login page branding.
If a theme is flagged as the default in System Global Settings, that theme is always used for the login page. If no default is specified, the VOSS theme is used as the fallback.
On a per-role basis, theme selection remains optional — if blank, the role inherits the global default theme.
Theme details tab
On the Theme Details tab of the Themes page you specify theme details:
Important
A Self-service theme can only be applied by selecting Interface as Self-service, uploading the required custom file and saving the theme.
Note
To set the default login page theme, system-level administrators can use System Global Settings in the Administration Tools menu. In the Portal Preferences, the dropdown fields Default Administration Theme and Default Self Service Theme control which theme is used for the login page.
Note that only system-level administrators can modify these settings.
Dark mode support
Themes can optionally support dark mode, providing a dark variant of the interface for user preference or to match their operating system or browser settings.
Enabling dark mode
To enable dark mode for a theme:
Edit the theme in the Admin Portal
Enable the Enable Dark Mode checkbox
This will enable the display of a Dark Mode color picker table where the theme's dark mode colors can be managed.
Both panels contain identical configuration options, allowing you to define distinct branding for each mode.
The admin UI dynamically shows or hides the dark mode panel based on whether Enable Dark Mode is enabled, and updates the labeling accordingly.
Configure the dark mode branding settings (colors and images)
edit screen toolbar:
If a dark theme palette is not available, the portal uses the light theme palette. If an individual colour/image value is not supplied in the active palette, the portal does not copy it from the other mode - CSS-level defaults or token-specific fallbacks apply where defined.
Users can set the theme mode in two ways:
For consistent appearance, fill in all color and image fields explicitly for both light and dark modes.
Disabling dark mode
Note
When dark mode is disabled, the gear icon context menu and the account preferences settings do not display theme modes to select from, as only light mode is configurable.
When Enable Dark Mode is not enabled, the theme operates in light mode only. After upgrading, existing themes remain light-only until an administrator enables dark mode and configures the dark mode branding.
Note
Dashboard widgets allow for custom color mapping, including dark mode mapping. These settings are not affected by the theme.
Related topics
Color Mapping in the Core Feature Guide
Branding tab
On the Branding tab you can customize a theme for your organization. You can change colors via the color picker or by typing in the color hex value. When no colors are chosen in this tab, the defaults apply.
Fonts
The Font dropdown allows for a selected font to override the global default Roboto font. The selected font is then applied to all text, including the login screen.
Uploading images
When uploading images for the theme:
Note file size and width x height pixel dimension size restrictions. A system message displays if the image is too large.
Only PNG files are supported for the Logo image. Other images can be PNG or JPEG.
For image filenames, you can use the following characters and character types:
ALPHA / DIGIT / "-" / "." / "_" / "~"/ "#"
Image details
Login page details tab
The Login Page Details tab defines the theme for the Login page, including the title and banner text, cookie policy and privacy policy details.
If you add banner text (limited to 2048 characters), this is used at the bottom of the Login page.
References to the cookie policy and privacy policy in the Banner Text field should be added as placeholders, which will then resolve to the Cookie Policy and Privacy Policy data entered. The placeholders are:
Note
You can add multiple lines for the banner text, including paragraphs. Banner text displays exactly as you add it to this field. Cookie and security references show as links that open in a new browser tab.
Tip
Use the Action search to navigate Automate
This topic describes what each theme colour setting is for in the theme editor or saved theme data. See: Create a Theme in the Business Admin Portal.
Quick map (setting and typical UI area)
| Setting | Typical UI area |
|---|---|
| Primary / primary text | Brand, primary buttons, strong branded surfaces |
| Accent / accent text | Selection, highlights, active list/menu emphasis |
| Topbar / topbar text | Top strip of the app |
| Menu / menu text | Side navigation |
| Panel / panel text | Forms, tables, dialogs - main content surfaces; hierarchy tree labels |
| Background | Page canvas behind layout |
| Input / input text | Fields and editors |
| Button background | Solid action buttons |
| Highlight text | Text on selected table/list rows |
| Panel header bg / header text | Panel title bar strip and its wording |
| Paginator text | Table/list pagination labels |
| notification | Toast / message severity chrome |
Detailed colour reference
Primary colour (primary_colour)
The main brand colour - the strongest "this is our product" tint. It appears on primary actions, key branding strips, many focus and active states, and other surfaces where the UI should read as "the official brand colour."
Primary text colour (primary_text_colour)
The colour of text and icons drawn on top of primary-coloured surfaces (for example labels on a solid primary button, or wording on a primary-tinted header). It exists so foreground and background stay readable when you change the primary fill.
Accent colour (accent_colour)
A second strong colour used where the UI needs to say "selected," "highlighted," or "emphasised" without reusing the same swatch as primary. Typical uses include selected rows in tables and lists, active items in menus or pickers, and other "this thing is currently chosen" affordances.
Accent text colour (accent_text_colour)
The colour of text and icons on top of accent-coloured backgrounds - for example the label on a selected table row when the row background uses the accent colour.
Topbar colour (topbar_colour)
The background of the top application bar - the horizontal strip at the very top of the portal (often logo, global search, environment or user controls). It is usually distinct from the main page background so the bar reads as fixed chrome.
Topbar text colour (topbar_text_colour)
The colour of text and icons in that top bar (labels, icons, and similar elements sitting on topbar_colour).
Menu colour (menu_colour)
The background of the main navigation menu (typically the vertical sidebar with module links). It sets the "menu panel" feel separate from the central panel and page areas.
Menu text colour (menu_text_colour)
The colour of menu labels, icons, and similar elements drawn on menu_colour - including inactive items unless another state colour overrides them for a specific interaction.
Panel colour (panel_colour)
The background of content panels - cards, form areas, dialog bodies, and similar "work surfaces" where most reading and data entry happens. It is the usual large neutral (or tinted) surface behind tables and forms.
Panel text colour (panel_text_colour)
The default text colour for body content on panels - paragraphs, labels, table cell text, and general wording that sits on panel_colour (unless a more specific token applies to a sub-widget). In the portal it is also used for selectable hierarchy / organisation tree labels (there is no separate Theme key for tree text).
Background colour (background_colour)
The page-level backdrop behind the main layout - the colour users perceive as the outer application background outside or around panels and the menu. It is typically calmer or darker/lighter than panel_colour so panels and the menu lift visually.
Input colour (input_colour)
The fill background of text inputs - single-line fields, text areas, and similar editable controls (often aligned with dropdown surfaces in the same theme family).
Input text colour (input_text_colour)
The colour of typed text (and related foreground) inside those input controls - chosen so characters stay readable on input_colour.
Button background colour (button_background_colour)
The fill for standard solid action buttons (primary-style buttons used across the app). It can match primary or be set on its own when primary sits very close to panel fills in dark themes and buttons would otherwise look flat or hard to spot.
Highlight text colour (highlight_text_colour)
The colour of text and icons on top of highlighted (selected) rows in tables and lists - the wording that sits on the coloured selection strip (often driven by accent).
Panel header background colour (panel_header_background_colour)
The background of the title strip at the top of a panel - the bar behind the panel title, not the main panel body (panel_colour).
Panel header text colour (panel_header_text_colour)
The colour of the title wording (and related icons) on that panel header strip, so titles stay readable when the header background differs from the panel body.
Paginator text colour (paginator_text_colour)
The colour of pagination wording - page numbers, "rows per page", and similar labels in paginator controls (usually at the bottom of tables and lists).
Info notification colour (info_notification_colour)
The background of informational notifications (neutral "here is something you should know" messages).
Info notification text colour (info_notification_text_colour)
The text (and icon tint where applicable) on top of info notification backgrounds.
Success notification colour (success_notification_colour)
The background of success notifications (completed actions, confirmations, positive outcomes).
Success notification text colour (success_notification_text_colour)
The text on top of success notification backgrounds.
Warning notification colour (warn_notification_colour)
The background of warning notifications (caution, validation warnings, non-blocking issues).
Warning notification text colour (warn_notification_text_colour)
The text on top of warning notification backgrounds.
Error notification colour (error_notification_colour)
The background of error notifications (failures, blocking problems, destructive outcomes).
Error notification text colour (error_notification_text_colour)
The text on top of error notification backgrounds.
| Title | Description | Details |
|---|