Overview

To customize the colors, text colors, fonts, buttons, launch screen, background images, and components that appear in your mobile app, you’ll edit your theme file.

The default theme file is institutions/mxmobile/config/themes/theme_light.json, but you can add new themes and change which theme is displayed by default.

Definitions

Definitions are referenced throughout your theme file and are mainly used by components in the components section. You can change these definitions to change your app’s appearance.

Colors

In your theme file, search for colors to change the colors used throughout your app.

institutions/mxmobile/config/themes/theme_light.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

"colors": {
    "UNKNOWN_COLOR": "#FF00FF",
    "PRIMARY_100": "#9C42F6",
    "PRIMARY_200": "#9C42F6",
    "PRIMARY_300": "#9C42F6",
    "PRIMARY_400": "#9C42F6",
    "PRIMARY_500": "#9C42F6",
    "WHITE": "#FFFFFF",
    "NEUTRAL_100": "#F8F9FB",
    "NEUTRAL_200": "#EEF1F6",
    "NEUTRAL_300": "#E4E8EE",
    "NEUTRAL_400": "#CDD3DD",
    "NEUTRAL_500": "#A8B1BD",
    "NEUTRAL_600": "#6A7381",
    "NEUTRAL_700": "#49505A",
    ...

Visit our reference to see all the color definitions you can set and what their default uses are.

Each color family (primary, neutral, warning) has multiple values (100, 200, 300, etc.). These values represent one color.

Color Family Suggestions
Primary If your primary brand color is green, then your primary color values should be various shades of your green brand color. We commonly reference 300 values as the default. Lower values (100, 200) are used for lighter shades. Higher values (400, 500) are used for darker shades.
Secondary If you have a secondary brand color, it should be added as an accent color. You should set your main accent color in ACCENT_COLOR_1_300, then set the two lighter shades in the 100 and 200 values and the two darker shades in the 400 and 500 values.
Success Use success colors to communicate success states or other positive messaging.
Warning Use warning colors to draw attention to important elements or encourage the user to act with caution. Take special care when using warning colors to ensure contrast requirements are met.
Error Use error colors to communicate error states or destructive actions. Error colors should be used sparingly because they strongly pull the user’s attention.
Neutral Use subtle shifts in value to help organize content into distinct zones.

Text Colors

In your theme file, search for text_color_definitions to change the colors of your text conditionally.

institutions/mxmobile/config/themes/theme_light.json

1
2
3
4
5
6
7
8
9
10
11
12

"text_color_definitions": {
    "STANDARD": "NEUTRAL_900",
    "PRIMARY": "PRIMARY_300",
    "SECONDARY": "NEUTRAL_600",
    "HIGHLIGHT": "WHITE",
    "DESTRUCTIVE": "ERROR_300",
    "SUCCESS": "SUCCESS_300",
    "DISABLED": "NEUTRAL_500",
    "GAINS": "SUCCESS_300",
    "LIABILITIES": "ERROR_300",
    "ACCENT": "ACCENT_COLOR_1_300"
  },

Visit our reference to see all the text color definitions you can set and what their default uses are.

Fonts

In your theme file, search for font_definitions to change properties within your text elements.

institutions/mxmobile/config/themes/theme_light.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

"font_definitions": {
    "H1": {
      "font_name": "ProximaNova-Bold.ttf",
      "font_size": 32,
      "markdown_semibold": "ProximaNova-Semibold.ttf",
      "markdown_bold": "ProximaNova-Bold.ttf",
      "markdown_italic": "ProximaNova-RegularIt.ttf"
    },
    "H2": {
      "font_name": "ProximaNova-Bold.ttf",
      "font_size": 24,
      "markdown_semibold": "ProximaNova-Semibold.ttf",
      "markdown_bold": "ProximaNova-Bold.ttf",
      "markdown_italic": "ProximaNova-RegularIt.ttf"
    },
    ...

If you haven’t already, and would like to, you can add a font.

Visit our reference to see all the font definitions you can set and what their default uses are.

Opacities

In your theme file, search for opacities to change the various opacity values that the components use.

institutions/mxmobile/config/themes/theme_light.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14

"opacities": {
    "BAR_GRAPH": 128,
    "DARK_SCRIM": 225,
    "MEDIUM_SCRIM": 150,
    "LIGHT_SCRIM": 70,
    "BUDGET_ARC_BACKGROUND": 63,
    "HEADER": 51,
    "DISABLED_OPACITY": 51,
    "HEAVY_CLICK_INDICATOR": 40,
    "LIGHT_CLICK_INDICATOR": 20,
    "HELP_POPUP_SCRIM": 255,
    "FULL": 255,
    "CLEAR": 0
  },

Values range from 0 (clear) to 255 (full).

Visit our reference to see all the opacity definitions you can set and what their default uses are.

Buttons

In your theme file, you can search for and customize specific buttons.

institutions/mxmobile/config/themes/theme_light.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

    "BUTTON_PRIMARY": {
      "fill_color": "PRIMARY_300",
      "stroke_color": "UNKNOWN_COLOR",
      "stroke_width": 0,
      "fill_opacity": 255,
      "radius": 6
    },
    "BUTTON_INVERSE": {
      "fill_color": "WHITE",
      "stroke_color": "UNKNOWN_COLOR",
      "stroke_width": 0,
      "fill_opacity": 255,
      "radius": 6
    },
    ...

All buttons also have a disabled type. A disabled button is unusable and unclickable.

Visit our reference to see all the buttons you can customize.

Native Styles

In your theme file, search for native_styles to customize your app’s launch screen.

institutions/mxmobile/config/themes/theme_light.json

1
2
3
4
5
6
7

"native_styles": {
    "keyboard_appearance": "DEFAULT",
    "launch_screen_style": {
      "background_color": "PRIMARY_300",
      "image_filepath": ""
    }
  },

You can change the background_color to one of the color definitions you set.

You can also add a launch screen image:

  1. Find the image_filepath key and change the corresponding value to your file name.
  2. Add your .png image to institutions/mxmobile/assets/mxmobile/hd/images.
  3. Run ./generate.

Background Images

You can customize the background image that is displayed throughout the app. There are 2 variants: background_portrait appears when the app is in a portrait orientation and background_landscape appears when the app is in a landscape orientation.

Screen Orientation Image Size (in pixels) Theme Configuration Key for Image Filename
Vertical
  • HD: 640x1136
  • SD: 320x568
 portrait_background_image_filename
Horizontal
  • HD: 2048x1536
  • SD: 1024x768
 landscape_background_image_filename

For more info on SD and HD images, view the images section.

How to Change a Background Image

  1. Open institutions/mxmobile/assets/mxmobile/ in Finder.
  2. Add your new background image files to the sd and hd folders to override the default images.
  3. If your file name differs from the default, change what the image path is set to in institutions/mxmobile/config/themes/theme_light.json.
  4. Run ./generate.

Add a Theme

You can add new themes for users to select. You can also select which theme is shown by default.

To add a new theme:

  1. After you’ve configured the default theme (light_theme.json) to your liking, copy light_theme.json and rename the copy to a name that reflects the theme’s purpose (for example, holiday_theme.json, promo_theme.json, or dark_theme.json).
  2. Open institutions/mxmobile/strings/master/en-US.json and copy the following JSON text:
institutions/mxmobile/strings/master/en-US.json
1
2
3
4
5
6
7
8
9
10
11
12
13

"Indeterminate" :
    {
      "Color Theme" :
      {
        "file" : "generated/models/helios/theme.h",
        "line" : 141,
        "Table" :
        {
          "COLOR_THEME_LIGHT"                                   : "Light",
          "COLOR_THEME_DARK"                                    : "Dark",
          "COLOR_THEME_<NEW_THEME_NAME>"                        : "New Theme"
        }
      },
  1. Replace <NEW_THEME_NAME> with the name of your theme in all capital letters. Enter the theme’s name for the string ("<New Theme Display Name>"), which sets the text for the theme option in the settings.
  1. In your new theme file, set:
    • id to any value that uniquely identifies your theme.
    • display_key to reference the COLOR_THEME_<NEW_THEME_NAME> key defined in en-US.json.
    • display_order to determine which theme is the default theme (starting at 0). Note: If changing the order, you’ll need to update any other theme files. If you change the order, make sure that all theme files have a unique display_order.
    • keyboard_appearance to either “DEFAULT” or “DARK”.
    • is_settings_option to true. This configuration displays the theme option in the settings.