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. While all theme files are the same, the only differences being the changes you make within them, these guides will reference theme_light.json.

You can learn to customize specific visuals within your features and views, such as front-facing text and images, in the features and views guide.


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.

After making changes, you can view a component’s new styles using our DevTools.

Themed Components in DevTools


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

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

Colors Definitions Section in Theme File

Color section in theme file

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 Neutral colors make use of 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 all your text.

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

Text Color Definitions Section in Theme File

Text color section in themes file


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

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.

Font Definitions Section in Theme File

Font section in theme file


In your theme file, search for opacities to change the opacities your components use.

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.

Opacities Definitions Section in Theme File

Opacities section in theme file


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

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.

Primary Button Section in Theme File

Primary button section in theme file

Native Styles

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

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

You can also add a launch screen image:

  1. Enter the image_filepath with your image name.
  2. Add your image to institutions/mxmobile/assets/mxmobile/hd/images.
  3. Run ./generate.

Native Styles Section in Theme File

Native styles section in theme file

Background Images

Background images allow for personalization in either a vertical or horizontal format (depending on the device’s orientation or size).

These images are used throughout the entire mobile app.

Screen Orientation Image Size (in pixels) Image File in Assets Image Path in theme_light.json
Vertical 640x1136 background_portrait.png portrait_background_image_filename
Horizontal 2048x1536 background_landscape.png landscape_background_image_filename

How to Change a Background Image

  1. Visit institutions/mxmobile/assets/mxmobile/.
  2. Replace the desired background image file in the sd and hd folders.

If your file name differs from the default, change what the image path is set to in institutions/mxmobile/config/themes/theme_light.json. Then, run ./generate.