Starting in Workspace 5.0, you can customize the colors of the user interface components used in Browser by defining a color theme. With Workspace 5.5, the use of themes includes Home and Storefront.

You can define and register a theme for a workspace platform. If you don't define a theme, you get a default palette.

Colors can be specified in the following ways:

• Hexadecimal, not case specific, 3 (#F0F) or 6 characters (#FF00FF)
• HSL/HSLA
• RGB/RBGA
• CSS color names — optional color properties only

The backgroundPrimary color property must be specified using a numeric format (that is, not a name); otherwise errors are thrown.

Starting in Workspace 10, your users can choose a light or dark color scheme, or the underlying OS color scheme. You can provide custom light and dark schemes as part of your custom theme, or you can define only a light scheme or a dark scheme to provide the same scheme to all your users.

You can also customize the location and UI string of the default Appearance menu. For details, see Customize light/dark scheme menu.

If a user's system contains multiple workspace platforms, each Workspace application (Browser, Home, and Storefront) retains the theme of the workspace platform it was opened with, until closed or changed. Therefore, the user's screen may show Workspace windows with different themes, depending on which workspace platform created each window.

Simple theming

The most straightforward way to define a theme is to define only the required properties:

• brandPrimary
• brandSecondary
• backgroundPrimary

All other properties then either are generated based on these color values or use default colors.

The properties background1 to background6 are generated based on backgroundPrimary. Internally, the backgroundPrimarycolor is translated into HSL format, and then other shades are generated by varying the saturation and lightness values. The following diagram shows how shades are generated based on the color red, which has a hue value of 352.

The generated values are used to provide depth for visual components, such as for drop shadows. Workspace selects between light shades and dark shades, depending on the operating system's color mode.

Other colors are generated from brandPrimary and brandSecondary. These include colors for active, hover, focused, and text.

Code example

const wp = WorkspacePlatform.init({
…
  theme: [
    {
      label: 'MyTheme',
      palette: {
        brandPrimary: '#0661DC',  // Hexadecimal, 3 or 6 digits
        brandSecondary: rgb(170, 136, 166) , // RGB, optional: rgba()
        backgroundPrimary:  hsl(3, 23%, 17%)  // HSL, optional: hsla()
      }
    }
  ],
});

UI mappings of required properties

Here are examples of the color properties that are required to be defined in a theme. In the screen shots, the color property is set to vermillion (#D55E00).

• brandPrimary
  Example: dialog box default button background

• brandSecondary
  Example: dialog box other button background

• backgroundPrimary
  Example: Used to generate background2, used in Browser page title bar background, focussed/selected view tab

Advanced theming

If you prefer, you can specify additional color properties, rather than using generated or default colors. For optional properties, you can use CSS named colors instead of numeric definitions.

background2:  'rebeccapurple'

Here are examples of optional color properties. In the screen shots, the color property is set to vermillion (#D55E00). For a complete list of properties, refer to the Workspace Platform API reference.

• inputBackground
  Example: Save As dialog box user input background

• background1
  Example: Browser view title bar background. Note that background1 is also used as the color of the static divider between Views in Pages.

• background2
  Example: Browser page title bar background, focussed/selected view tab

• background3
  Example:
  • Store search bar background. Note that background3 is also used as the color of the divider between Views in Pages when the user is dragging a View to rearrange it.

• background4
  Example:
  • focussed toolbar button

• sub-toolbar background

• dialog background

• background5
  Example: Back button in search

• background6
  Examples:
  • Browser sub-toolbar outline

• dialog box outline

• statusActive
  Example: Selected page tab background

• inputColor
  Example: input box text and caret color

• inputFocused
  Example: Outline around selected text box

• textDefault
  Examples:
• Browser title bar icons & controls, selected view tab text

• Dialog box message text

• textHelp
  Example: Browser unselected view tab text

Content backgrounds

Starting in Workspace 9.2, we've introduced a set of content background color properties to help you customize backgrounds not accounted for elsewhere. The only property currently implemented is contentBackground1, but four others, through contentBackground5, will be available as needed. contentBackground1 lets you customize the background color of the hero (or "header") in Store.

Example: