Themes in Jitterbit App Builder

Overview

A theme controls how an App Builder application visually appears in the UI layer. A theme is a pairing of components and style types (previously known as value types) that lets you control the appearance of defined areas of the UI. For example, you might set the background color (a style type) of the Links area (a component) to teal.

This page explains how themes work, how theme tokens simplify customization, and how to set up dark mode.

How themes work

A component represents an area in the UI that can have its properties changed (for instance, pages are components). Style types represent the specific properties that can be changed or defined (for instance, Background Color is a style type).

A new theme has no visible effect until you configure components in it. The colors chosen at a theme level don't automatically apply to any parts of the UI on their own. Without any theme applied, App Builder appears at the UI Layer level in a theme-less state with minimal stylization. Use a theme's Preview button to see how different screens and panels look with the theme applied, without needing to apply it first.

Several predefined base themes are shipped with App Builder which can easily be used by your application as is, or leveraged as a base theme which you can further customize. Beyond basic colors, components and style types let you style dozens of other areas and behaviors.

Components and subcomponents

A component is a part of the UI that can be styled, such as a page or panel. Each component is divided into subcomponents that you can style individually, such as a panel's title bar or the links in a page's title bar.

To see custom colors through the UI Layer, configure the Components and Subcomponents panels. The following screenshot shows the Page - Title Bar component's Links subcomponent with its Background Color set to teal:

See the Component reference for the complete list of components and subcomponents.

Style types

With a component and subcomponent specified, you choose a style type from the Style Type field to apply a property. Style types can refer to font colors, background colors, images, alignment, gradient information, size information, and more, depending on which subcomponent you're customizing. Each style type's help text in the Style Type field describes the specific values it expects.

See the Style type reference for the complete list.

Theme tokens

A token is a named, reusable value, such as a color, text setting, or image, that a style can reference instead of a hardcoded value. Reference a token in a style value using {TokenName} syntax:

System tokens

Every theme includes a set of system tokens supplied by the platform. System tokens have a dot to the left of their name in the Tokens grid, and their names are universal across all themes:

• BackgroundColor
• BorderColor
• CautionColor
• ComplementaryColor
• DangerColor
• ForegroundColor
• PageBackgroundColor
• PrimaryColor
• SecondaryColor

Colors set directly in the theme editor appear as these system tokens in the Tokens grid. The {TokenName} syntax is the same reserved syntax previously available only for the PrimaryColor, SecondaryColor, and ComplementaryColor tokens.

Custom tokens

You can also add custom tokens to a theme for your own colors, text settings, and images, referenced the same way as {TokenName}. To edit tokens, click the list icon to the right of the Tokens title. This opens the Tokens dialog:

The Tokens grid groups tokens on three tabs:

• Colors: Color values. A token with no color set shows a preview of hashmarks.
• Text: Text settings such as Border Radius or Font Family. Each text token has a Style property, which controls which style lists the token appears in when you're setting a style.
• Images: Image values entered as CSS, such as linear-gradient(to right, #FFD700, #1E90FF), not visual images uploaded to the collection.

Custom tokens defined on a base theme are also available to any theme built on top of it, without needing to redefine them. However, control-level themes used directly in the design of a specific Field, Panel, or similar control aren't tied to a main application theme, so they only offer system tokens when you're setting a style. If you know a control is using a specific theme you created, you can still type a custom token's name directly into a field's theme style as {MyCustomTokenName}, but if the application's theme later changes and the new theme is missing that token, the style won't render as expected.

Adjusting colors

Colors can be adjusted for brightness or darkness and opacity. This customization is available for any color token, including the system tokens, such as {PrimaryColor}, {SecondaryColor}, and {ComplementaryColor}.

To adjust color brightness and darkness, add a pipe character along with numeric decimal value (positive value to increase or negative value to darken the color). Expected values range from -.9 to .9.

Syntax: {PrimaryColor|.25} or {PrimaryColor|-.25}

For a theme that supports dark mode, add a second, comma-separated value to set a different adjustment for the dark variant. For example, {ForegroundColor|-.8} darkens a color, which works well for a light variant, but in a dark variant you probably want to lighten the color instead. Adding a second value sets the dark variant's adjustment: {ForegroundColor|-.8,.8} darkens the color for the light variant and lightens it for the dark variant.

To adjust color opacity, add the tilde character along with a numeric decimal value. Expected values range from .1 to .9.

Syntax: {PrimaryColor~.25}

Dark mode

A theme's Supports Dark setting controls whether that theme can render in dark mode, and each user's Color Scheme preference, set on the User Profile page, controls when dark mode is requested. As a developer, you choose which themes support dark mode and define the dark colors and images those themes use. See Theme tokens for how a single theme stores both its light and dark values.

How a user's Color Scheme is applied

Users choose one of the following options for their account's Color Scheme:

A theme only renders dark if it supports dark mode. If a user prefers Dark but an element's theme doesn't support dark mode, that element stays light, so a single screen can mix both appearances. For example, the main application can be dark while a pop-up page that uses a different theme that doesn't support dark mode stays light, such as the User Profile pop-up opened from the action drawer.

Light is the default Color Scheme for new users.

Set up dark mode for a theme

To ensure dark mode is enabled for a theme, follow these steps:

1. Open the theme in the theme editor.
2. Enable the Supports Dark setting.
3. Click the list icon to the right of the Tokens title to open the Tokens dialog.
4. On the Colors and Images tabs, enter a Light value and a Dark value for each token. A Text token has a single value shared by both modes.

Collection images and dark mode

Collection images aren't connected to a theme; they're defined in a collection and used directly in the Workbench when building a page. Because of this, a theme's Supports Dark setting has no direct effect on collection images used in an application.

Instead, each collection image can link to a Dark Image variant. When an application page renders, App Builder looks at the user's Color Scheme preference and whether the active theme supports dark mode. If the image is being rendered in a dark theme mode and a Dark Image is linked, the linked dark variant renders instead of the normal image.

To link a dark variant to a collection image:

1. Upload the image to use as the dark variant to the same collection as the original image. See Upload the logo to a collection for the upload steps.
2. Navigate to the collection's Look & Feel, click the Images tab, and open the record for the original image.
3. Click Edit.
4. In the Dark Image field, select the dark variant.
5. Click Save.

For an edge case where you don't want the dark variant to render even though an image has a Dark Image linked, such as a list control where the exact image must match what the user selected, see Disable the dark image variant.

Elements that don't change in dark mode

The following elements don't change when a user's Color Scheme calls for dark:

• Elements styled by a theme that doesn't support dark mode. For example, a pop-up page that uses a theme without dark mode support stays light even while the main application is dark.
• Collection images with no Dark Image linked.
• Images rendered from application data, such as employee photos. These images have no dark variant.

Copy feature

Any theme can be copied. Because styles reference tokens rather than hardcoded values, you can often restyle a copy by changing only its token values, such as PrimaryColor, SecondaryColor, and ComplementaryColor. There are many predefined themes available that can be selected and used as is or customized further to get up and running quickly.

App Builder predefined themes

App Builder ships with several predefined themes. Although these are technically editable, when you upgrade any changes will be lost. Copy a predefined theme to preserve your changes across an upgrade.

The predefined Dark theme is a fixed dark-colored theme and does not respond to a user's Color Scheme preference. To make a theme switch between light and dark values, see Dark mode instead.

Since App Builder 4.67, the predefined Light, Dark, Shapes, Violet, Gradient, Light - Modern, and Login Base Theme themes each include a pre-built mobile theme, already set as that theme's mobile theme so it applies automatically on small screens. These mobile themes are optimized for mobile use out of the box, with the following adjustments:

• Touch-friendly hit targets, with a minimum size of 44x44 pixels.
• Mobile-scaled typography and line heights.
• Compact padding and margins.
• Single-column form field stacking.

This automatic behavior only applies to apps using one of these system themes directly. A custom theme based on a system theme does not inherit its predefined mobile theme. If you use a system theme directly and want to opt out of its predefined mobile theme, create a custom theme based on the system theme and use that instead; the predefined mobile theme does not carry over. If you already use a custom theme based on a system theme and want to adopt its predefined mobile theme, see Use a predefined mobile theme with a custom base theme.

See How to create a mobile theme to build a custom mobile theme instead.

Suggestions

If you specify a dark background color, ensure you use a font color that is readable for all text. Take advantage of the text-shadow property included in font color to add extra contrast. This is especially relevant when choosing a theme's dark variant colors.

Appendix

Component reference

Page

Page - Title Bar

Page - Tab Bar

Page - Action Drawer

Page Pop-up

Panel

Panel Placement

Panel - Toolbar

Panel - Filter

Panel - Single-row Panel

Panel - Board and Lane

Panel - Multi-row

Panel - Chart

Panel - Calendar

Group

Panel - Agent Chat

Control Containers

Controls

Validations

Login form

Style type (value type) reference