Theming system

Theming system

The theming system aims at providing an easy way for developers to find and use colors from designs inside the application. Any colors available inside the Firefox application will be one of the available Firefox colors. Designers then decide which of those colors will be used in their designs, and create different mobile styles. Mobile styles defines how theming is applied inside the application, for example by applying a certain color for actions or icons. Any colors we use in our application needs to be defined in the iOS mobile theme. There's currently light theme and dark theme in our application, but more could eventually come.

How theming works

The ThemeManager manages and saves the current theme. By default it's set to be the OS theme (light or dark) but can be changed overridden by the user in the settings either through brightness or selecting directly the wanted theme. Another way to set the theme is through night mode. By selecting night mode we automatically apply the dark theme on the application (as well as in webviews but that is related to night mode and not the theme itself).

How to implement theming in code

From a developer perspective, theming is applied with view controllers. View controllers holds references to views which are theme.

1. First step in applying the theming system is to make your view controller follow the Themeable protocol. Preferably the themeManager and notificationCenter variables needs to be init injection so they're easier to integrate with unit tests.
2. You should then in viewDidLoad have a call to listenForThemeChange(). This will make sure your view controller applyTheme method will be called when there's a theme change inside the application.
3. Make any of your views follow the ThemeApplicable protocol. This protocol has a applyTheme(theme:) method that will be called automatically from the view controller when a theme change happens. This will not be called on cell/view creation thought so you need to make sure it's called once at init/configuration time.
4. Use applyTheme(theme:) to setup any labels, buttons, background view, spinners, borders, shadows colors.

Don't

• Don't add tokens for new colors in the Theme protocol if it's not in the iOS mobile theme.
• Don't use Firefox colors directly in code (aka, no FXColors.aColor should ever be referenced directly. Colors needs to be themed).

Do

• Do ask designers if a color in a design you need to implement is not in the mobile theme.
• Do use .clear color directly in code, this color isn't themed.
• For any image that requires theming, use ThemeType getThemedImageName(name:) method. Your image might need renaming to follow convention of adding _dark into the name of a dark themed image. Please use ImageIdentifiers for image name.

Migrating from legacy theming to the new theming system

• Remove any conformance to NotificationThemeable
• Views/cells shouldn't register for .DisplayThemeChanged. Only the view controller should be notified with notifications.
• There should be no more calls to UIColor.Photon or UIColor.theme.
• LegacyThemeManager should also not be used.

This is an example PR of a migration from legacy to new theming system for wallpaper selectors. The PR is for a small section of the app, so easier to understand than let's say the homepage migration PR.