Skip to main content

Version: 24.10

Theme

The Journey Applicants user interface (UI) design has been upgraded to include an enhanced theme engine. This upgrade allows for extensive customization, supporting both light and dark modes, component-specific styling, and global consistency in UI design. The theme engine introduces multiple levels of customization with a clear precedence system.

note

While themes can be defined in various ways, the global configuration (/configs/**/global.ts) is the preferred method and takes priority over all other configurations.

In this release, Journey Applicants has been re-developed to provide customizable theming options based on Material UI's Joy UI interface. Joy UI has CSS-based UI editing options that allow many UI elements to be modified to meet your needs.

Overview​

  • The theme engine supports global configurations and multiple override levels with /configs/**/global.ts as the preferred and highest priority method.
  • Theme configurations can also be defined in transact-config.json, or in organization or user properties, with higher-priority configurations overriding lower-priority configurations.
  • Use the theme configuration properties to create a clean, accessible, and brand-aligned user interface.
  • Comprehensive support for light and dark modes provides flexibility and promotes accessibility.
  • Component-specific customization allows granular control over UI styling.
  • CSS variables provide consistency and dynamic updates across themes.

Theme configuration levels​

The theme is defined using theme properties that can be defined in various ways, and these are applied according to the following order of precedence (highest priority to lowest priority).

  1. `configs//global.ts`** overrides everything, and is the preferred method for setting the theme.
  2. The theme user profile property in Journey Manager overrides all theme properties listed below.
  3. The Workspaces Theme organization property in Journey Manager overrides the values provided in transact-config.json.
  4. transact-config.json overrides the default colour.

If no theme is provided at any level, the default theme is applied, ensuring the UI remains functional and visually consistent.

Key theme properties​

The theme engine exposes the following properties for customization.

PropertyDescription
colorSchemesConfigure palettes for light and dark modes, including background, text, and component colors.
typographyDefine global font settings such as fontFamily, fontSize, and fontWeight.
componentsOverride styles for individual components.
spacingSet spacing units for consistent margins and paddings.
breakpointsCustomize responsive breakpoints for different screen sizes.

Theme colours​

Defining theme colours is simple using the visual color palette builder in Joy UI's theme builder interface. Once you've customized the theme variables using the theme builder, you can copy them and paste them under the colourSchemes property in your theme configuration file or property.

Light and dark modes​

The colorSchemes property supports separate configurations for light and dark modes. This allows for flexible palette definitions and promotes accessibility across different visual environments.

Example: Light and dark mode configuration
{
  "colorSchemes": {
    "light": {
      "palette": {
        "background": {
          "default": "#f5f5f5",
          "paper": "#ffffff"
        },
        "text": {
          "primary": "#000000",
          "secondary": "#757575"
        }
      }
    },
    "dark": {
      "palette": {
        "background": {
          "default": "#121212",
          "paper": "#1e1e1e"
        },
        "text": {
          "primary": "#ffffff",
          "secondary": "#b3b3b3"
        }
      }
    }
  }
}

Here's some information about how light and dark modes work.

  • Light and dark modes utilize separate palettes defined in the colorSchemes property.
  • CSS variables are dynamically applied based on the active mode's color scheme.
  • Component styles, such as buttons or cards, inherit palette definitions and can be further customized.

Customizing component styles​

The theme engine allows component-specific customization using the components property. This enables fine-grained control over the styles of individual UI components.

Example: Customizing button styles
{
  "components": {
    "Button": {
      "styleOverrides": {
        "root": {
          "borderRadius": "8px",
          "textTransform": "none",
          "padding": "12px 24px"
        }
      }
    }
  }
}

Here's some information about component customization.

  • The styleOverrides property allows you to override default style properties.
  • You can target specific components (for example, Button, Card, Typography) and adjust properties like padding, border radius, and colors. To learn more about Joy UI's component properties, see Joy UI > Themed components.
  • Styles are applied consistently across light and dark modes unless explicitly overridden.

CSS variables​

The theme engine leverages CSS variables to provide dynamic and consistent styling.

  • CSS variables are generated from the theme configuration; for example, palette colors or typography settings.
  • CSS variables ensure that colors, fonts, and spacing scale consistently across the UI.
  • Dynamic updates to themes (for example, switching between light and dark modes) are applied seamlessly without additional logic.
Example: Generated CSS variables
--palette-background-default: #f5f5f5;
--palette-background-paper: #ffffff;
--palette-text-primary: #000000;
--palette-text-secondary: #757575;

Default theme​

Use the default theme viewer below to explore the properties defined in the default theme object and their default values.

  • cssVarPrefix: "joy"

:::tip To create your own theme, start by customizing the theme colors. :::

Applying a theme​

To theme your Journey Applicants portal, create a theme file under the configuration theme folder and import the file to your global configuration.

src/configs/default/global.ts
import { Config } from '@journey-ui/workspaces/build/ap/types';
import theme from './themes/default';

export const globalConfig = ({ date }: any): Config => ({
  theme,
  ...
});

export default globalConfig;
src/configs/default/themes/default.ts
export const defaultTheme = {
  colorSchemes: {
    light: {
      palette: {
        primary: {
          50: '#E3E7F1',
          100: '#BCC9E1',
          200: '#91AAD0',
          300: '#618BBE',
          400: '#3A6DAC',
          500: '#174F9A',
          600: '#154489',
          700: '#113671',
          800: '#0C2A5A',
          900: '#081D42',
        },
        background: {
          body: `linear-gradient(to bottom, var(--joy-palette-primary-600), var(--joy-palette-primary-900) 300px, var(--joy-palette-background-level1) 300px)`,
          surface: '#FFFFFF',
          level1: '#F0F3FA',
          level2: '#E3E7F1',
          backdrop: `linear-gradient(to bottom, var(--joy-palette-primary-600), var(--joy-palette-primary-900) 300px, var(--joy-palette-background-level1) 300px)`,
        },
        text: {
          primary: '#1C2234',
          secondary: '#4D576C',
          tertiary: '#7A869B',
        },
        success: {
          mainChannel: '#4CAF50',
        },
        warning: {
          mainChannel: '#F0AD4E',
        },
        common: {
          white: '#ffffff',
        },
      },
    },
  },
  breakpoints: {
    values: {
      xs: 0,
      sm: 650,
      md: 900,
      lg: 1200,
      xl: 1536,
    },
  },
  fontFamily: {
    body: '"Roboto", "Helvetica", "Arial", sans-serif',
    display: '"Roboto", "Helvetica", "Arial", sans-serif',
  },
  fontSize: {
    xl: '1.00rem',
    xl2: '1.10rem',
    xl3: '1.50rem',
    xl4: '1.75rem',
    lg: '1.00rem',
    md: '0.95rem',
    sm: '0.85rem',
    xs: '0.75rem',
  },

  fontWeight: {
    lg: 600,
    md: 500,
    sm: 300,
  },
  typography: {
    h1: {
      fontWeight: 'normal',
      color: 'var(--joy-palette-primary-600)',
      fontSize: 'var(--joy-fontSize-xl4, 2.25rem)',
    },
    h2: {
      fontWeight: 'normal',
      color: 'var(--joy-palette-primary-600)',
      fontSize: 'var(--joy-fontSize-xl3, 1.875rem)',
    },
    h3: {
      fontWeight: 'normal',
      color: 'var(--joy-palette-primary-600)',
      fontSize: 'var(--joy-fontSize-xl2, 1.5rem)',
    },
    h4: {
      fontWeight: 'normal',
      color: 'var(--joy-palette-neutral-600)',
      fontSize: 'var(--joy-fontSize-xl, 1.25rem)',
    },
    'title-md': {
      fontWeight: '500',
      color: 'var(--joy-palette-neutral-600)',
      fontSize: 'var(--joy-fontSize-sm, 1rem)',
    },
    'body-md': {
      fontWeight: '300',
      color: 'var(--joy-palette-neutral-600)',
      fontSize: 'var(--joy-fontSize-sm, 1rem)',
    },
  },
  components: {
    JoyButton: {
      styleOverrides: {
        root: {
          borderRadius: '6px',
          textTransform: 'none',
          fontWeight: 500,
          backgroundColor: 'transparent',
        },
        solid: {
          color: '#FFFFFF',
          '&:hover': {
            backgroundColor: 'color-mix(in srgb, var(--joy-palette-warning-main) 85%, black)',
          },
        },
      },
    },
    JoyTooltip: {
      styleOverrides: {
        root: {
          borderRadius: '0.375rem',
          boxShadow: '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
          color: '#fff',
          backgroundColor: 'var(--joy-palette-primary-600)',
        },
      },
    },
    JoyStepper: {
      styleOverrides: {
        root: {
          '--Stepper-verticalGap': '4rem',
          '--StepIndicator-size': '1.75rem',
        },
      },
    },
    JoyStepIndicator: {
      styleOverrides: {
        root: {
          'background-color': 'var(--joy-palette-success-300)',
          '--StepIndicator-size': '1.75rem',
        },
      },
    },
    JoyGrid: {
      styleOverrides: {
        root: {
          '--Grid-rowSpacingLevel2': '42px',
        },
      },
    },
    JoyTable: {
      styleOverrides: {
        root: {
          '--Table-headerUnderlineThickness': '0px',
          '--TableCell-paddingX': '0rem',
          'table-layout': 'auto',
        },
      },
    },
    // ... other component styles remain unchanged
  },
};

export default defaultTheme;

Attributes​

To review the list of supported attributes, see API Reference.