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

A. UIView & UIViewController

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(view). 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.

B. SwiftUI View

SwiftUI theming works slightly differently by leveraging Apple’s environment values struct (EnvironmentValues). We define values in the struct and to read a value from the structure, we declare a property using the Environment property wrapper and specify the value’s key path.

Note: This is currently only available in iOS 14.0 hence the use of if #available(iOS 14.0, *) below.

Below is a sample with steps on how to add theming for SwiftUI.

import Foundation
import SwiftUI
import Shared

struct SampleView: View, ThemeApplicable {
    /// Step 1:
    /// Add SwiftUI Theming using `themeType` Environment variable
    @Environment(\.themeType) var themeVal

    /// Step 2:
    /// Add required state variables for associated colors that require
    /// theme updates and define default value
    @State var btnColor: Color = .green

    var body: some View {
        VStack(spacing: 11) {
            Button("SampleButton") {
                // Do some work
                print("Sample Button Pressed")
            }
            /// Step 3:
            /// Assign state color variables to the view
            .foregroundColor(btnColor)
        }
        .onAppear {
            /// Step 4:
            /// If there is an initial theme update then we perform it here
            applyTheme(theme: themeVal.theme)
        }
        .onChange(of: themeVal) { val in
            /// Step 5:
            /// When the themeType gets updated we
            /// listen to the change via `onChange` method
            /// attached to the whole view and perform
            /// required updates to the state color variables
            applyTheme(theme: val.theme)
        }
    }

    /// Step 6:
    /// For better cleanup add applyTheme method using ThemeApplicable protocol
    func applyTheme(theme: Theme) {
        let color = theme.colors
        btnColor = Color(color.actionPrimary)
    }
}

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.