Skip to content

Images

Jump to bottom
Winnie Teichmann edited this page Jan 12, 2026 · 5 revisions

Overview

This document describes how images are managed in the Mozilla iOS codebase. There are two categories of images:

  • Standard Images – shared, cross-platform icons from Mozilla’s design system (Acorn)
  • Normal Images – all other images that are not part of Acorn

Each category has different rules for adding and maintaining assets.

Standard Images (Acorn icons)

Mozilla iOS uses a shared set of standardized icons from Mozilla’s design system so icons look consistent across platforms and we avoid duplicates. These icons live in the Acorn repository.

When you need a new icon always check first:

  1. Does an equivalent icon already exist in the iOS project asset catalog?
  2. If not, does it exist in Acorn? If an Acorn icon exists, use that instead of adding a one-off image from design.

How to add a Standard Image

  1. Find the icon in Acorn

    • Locate the icon in the Acorn repo.
    • Confirm there isn’t already a matching icon in the iOS project (search the asset catalog and StandardImageIdentifiers).

  2. Add the icon as a new Image Set in the asset catalog

    • In Xcode, open the app’s Images.xcassets.
    • Create a New Image Set.
    • Name the image set exactly like the Acorn icon name, including the size suffix, for example:
      • settingsLarge
    • Do not put Acorn icons into subfolders inside the asset catalog. Keep them at the top level.

  3. Configure the Image Set correctly

    • Inside the Image Set settings:
    • Use a single scale (one PDF).
    • Add the icon as a PDF.
    • Check “Preserve Vector Data”.

  4. Register the icon in StandardImageIdentifiers After the Image Set exists, add the icon identifier to StandardImageIdentifiers. For that please follow this documentation.

  5. Verify usage

    • Build the app and confirm the icon renders at the expected size.
    • If the icon is used with tinting, confirm it tints correctly (see multi-color note below).

Important notes and edge cases

Avoid duplicates If a designer provides an image that matches an existing Acorn icon (or one already in the project), do not add it - use the existing standard icon instead.

Multi-color Acorn icons Some Acorn icons contain multiple colors. iOS cannot change the colors of a multi-color assets. If you need a tinted version (e.g. light/dark version) and the Acorn icon is multi-color:

  • Request a appropriate tinted asset from design (in the desired color/tint).

Adding light and dark variants

Some standard images require different artwork for light and dark appearance modes (for example lockSlashLarge). In this case, only one Image Set is still used.

Follow the standard steps above with the following adjustments:

Image Set configuration

  • Create a single Image Set named after the base icon (e.g. lockSlashLarge).
  • In the Image Set settings, configure Appearances to:
    • Any, Dark

Image assets

  • Add the light version of the image to the Any appearance.
  • Add the dark version of the image to the Dark appearance.
  • Both images should be added as PDFs, using a single scale, with “Preserve Vector Data” checked.

Naming of source files The underlying PDF files should include a suffix indicating their variant:

  • lockSlashLargeLight
  • lockSlashLargeDark

These suffixes are only for the source image files. The Image Set name and the identifier in StandardImageIdentifiers do not change and continue to use the base name (lockSlashLarge).

Import script (automatic updates from Acorn)

Mozilla iOS uses an automated import script to keep all standard images in sync with the Acorn repository.

  • A GitHub Action runs once per week.
  • The script compares the Acorn repository with the icons currently in the iOS project.
  • If any standard images have changed in Acorn, the script automatically updates the corresponding assets in the project.

For this process to work correctly, strict adherence to the naming and structure rules described in this document is required:

  • Image set names must exactly match the Acorn icon names (including size suffixes).
  • Icons names must match the Acorn icon names.
  • Icons must not be placed in subfolders inside the asset catalog.
  • Icons must be added as PDFs with “Preserve Vector Data” enabled.

If these conventions are not followed, the script will not be able to detect or update the images automatically.

Normal Images (non-standard images)

Any image that does not exist in the Acorn repository is considered a normal image.

Normal images are typically feature-specific assets, illustrations, or one-off images that are not part of Mozilla’s shared design system.

Adding normal images

  • Normal images are added to Images.xcassets.
  • Unlike standard images:
    • There are no required naming conventions.
    • Images may be placed in folders inside the asset catalog.
    • Images do not need to follow Acorn size or structure rules.

Registering normal images

  • Every normal image must be added to ImageIdentifiers.
  • Identifier names should clearly describe the image’s purpose.
  • Follow existing ordering and grouping conventions in ImageIdentifiers.

Important distinction

  • Normal images must not be added to StandardImageIdentifiers.
  • If an image later becomes part of Acorn, it should be migrated to a Standard Image following the rules above.

Clone this wiki locally