Theming

In OneCX, theming controls how the content of a page looks. The OneCX shell, working together with the OneCX Theme Management application, provides the theme. A theme’s look is expressed as a set of CSS variables (design tokens) — OneCX’s own suite of theme variables. Each workspace can use a different theme, and the theme’s variables are exposed on every page — with different values depending on the workspace being accessed.

How theming works

The shell makes the active theme’s variables available on the page automatically, based on the workspace being accessed. An application does not have to do anything to apply a theme — there is no import, provider, or build step on its side.

Regardless of whether an application is built with Angular or React, consuming a theme is the same thing: reference the corresponding CSS variable in the application’s own styles, as shown in Utilizing Theme Variables below.

What an application must do

The only responsibility of a OneCX-compatible application is to use the theme variables in its own styles instead of hard-coded color, font, or spacing values. Doing so means the application automatically adopts whatever theme is active for the workspace and restyles itself when the theme changes. Hard-coded styles, by contrast, do not follow the active theme and look out of place when the theme differs.

Theme Variables

Theme variables are CSS variables available on the page for any application.

Below is a list of the theme variables available on the page:

Basic Variables

CSS variable

Description

--primary-color

Primary color of non-text content.

--secondary-color

Secondary color of non-text content.

--content-bg-color

Default background color of non-text content.

--content-alt-bg-color

Alternate background color of non-text content.

--hover-bg-color

Default background color on hover of non-text content.
Text-related Variables

CSS variable

Description

--font-family

Default font family for text content.

--font-size

Default font size for text content.

--text-color

Primary font text color.

--text-secondary-color

Secondary font text color for elements in lower design hierarchy, usually less prominent.

--solid-surface-text-color

Font text color on solid (opaque) surfaces.
Button-related Variables

CSS variable

Description

--button-hover-bg

Background color of a button in hover state.

--button-active-bg

Background color of a button in active state.

--danger-button-bg

Background color of a button with danger severity.
Message-related Variables

CSS variable

Description

--info-message-bg

Background color of a message with info severity.

--success-message-bg

Background color of a message with success severity.

--warning-message-bg

Background color of a message with warning severity.

--error-message-bg

Background color of a message with error severity.
Misc Variables

CSS variable

Description

--divider-color

Color of divider HTML elements, such as <hr> or component borders.

--body-bg-color

Background color of the document’s body, used for the content pane’s background color.

--overlay-content-bg-color

Background color of the overlays.
Topbar Variables

CSS variable

Description

--topbar-bg-color

Background color of the topbar.

--topbar-left-bg-color

Background color of the topbar’s left side.

--topbar-text-color

Color of the text in the topbar.

--topbar-item-text-color

Color of the text of the items located in the topbar.

--topbar-item-text-hover-bg-color

Background color for the items located in the topbar on hover state.

--topbar-menu-button-bg-color

Background color of the vertical menu hiding toggle.

--topbar-menu-button-text-color

Color of the text in the vertical menu hiding toggle.

--logo-color

Color of the topbar’s logo.

CSS variable

Description

--menu-bg-color

Background color of the sidebar (left side of the shell).

--menu-text-color

Text color of the menu, located in the sidebar (left side of the shell).

--menu-item-text-color

Text color of the menu item, located in the sidebar (left side of the shell).

--menu-item-bg-color

Background color of the menu item, located in the sidebar (left side of the shell).

--menu-item-hover-bg-color

Background color of the menu item in hover state, located in the sidebar (left side of the shell).

--menu-active-item-text-color

Text color of the menu item in active state, located in the sidebar (left side of the shell).

--menu-active-item-bg-color

Background color of the menu item in active state, located in the sidebar (left side of the shell).

--menu-inline-border-color

Border color of the inline menu, located in the sidebar (left side of the shell).

Utilizing Theme Variables

Regardless of whether your application is built with Angular or React, using a theme variable just means referencing the corresponding CSS variable in your styles — injecting and applying the variables' values is handled automatically. When creating styles for UI components, it’s important to consider whether a style should be theme-aware. Example of a stylesheet using a theme variable:

styles.css
button {
    background-color: var(--primary-color);
}

The example above sets the background color for each button element to the value corresponding to the --primary-color theme variable.

To apply a theme to an application step by step, see Apply Theming and Expose Component Styles.

For details on customizing the OneCX PrimeNG theme, see the PrimeNG Theming Customization feature page for how the OneCX theme maps to PrimeNG and how to apply optional token overrides.