Firefox Brand

A tool for generating Firefox brand folder content in all its variations from a smaller set of source assets. This generator processes brand configurations to produce complete branding packages for different Firefox distributions.

Usage

Run from anywhere inside the repo — the tool walks up to find the repo root (a directory containing config.json and brands/).

# Build every brand under brands/
firefox-brand-generator

# Build a specific brand
firefox-brand-generator official
firefox-brand-generator nightly

# Only run specific transformation types
firefox-brand-generator official --only copy-preprocess,raster

# Override the repo root (if auto-detection doesn't apply)
firefox-brand-generator --root /path/to/repo

# Override the output directory (default is <root>/dist)
firefox-brand-generator official -o /tmp/build

Derived paths for each brand:

• Config: {root}/config.json
• Source: {root}/brands/{brand}/
• Static: {root}/static/
• Output: {output}/{brand}/ (defaults to {root}/dist/{brand}/)

Options

• [BRAND] - Brand to build. Omit to build all brands found under {root}/brands/
• --root <DIR> - Repo root override (auto-detected by default)
• -o, --output <DIR> - Output parent directory (default: {root}/dist). Each brand is written to <DIR>/<BRAND>/
• --mac <MODE> - Control macOS-specific transformations
  • none - Skip all macOS-specific operations
  • simple - Run icns, assets-car only
  • all - Run icns, assets-car, ds-store
  • If not specified, defaults to simple on macOS and none on other platforms
• --only <TYPES> - Comma-separated list of transformation types to run
  • Available types: raster, ico, icns, assets-car, copy, copy-preprocess, ds-store
  • When specified, only these types will be run and --mac is ignored
• -h, --help - Print help information
• -V, --version - Print version information

Updating Firefox branding

The generator's dist/<brand>/ output is structured to be a drop-in replacement for the corresponding browser/branding/<brand>/ directory in mozilla-central — the folder layout, filenames, and relative paths match, including the per-brand moz.build, jar.mn, locales/, content/, and platform-specific subfolders.

To regenerate assets, run firefox-brand-generator --mac all on macOS so the full set is produced (the macOS-only outputs *.icns, Assets.car, and dsstore are skipped on Linux, leaving a Linux-built dist/ incomplete for a Firefox update). The result mirrors browser/branding/<brand>/ file-for-file, so updating Firefox is a matter of copying the changed files from dist/<brand>/ to the matching paths in your Firefox checkout.

Notes:

• Upstream Firefox: the existing branding assets in mozilla-central predate this generator, so even when an asset's visual content is unchanged, the regenerated binary will be very similar but not identical. To keep diffs minimal and reviewable, only replace files that have actually changed. Don't bulk-overwrite the directory just because the tool produced a fresh version.
• Firefox forks can add their own brand by creating a new directory under brands/<your-brand>/ mirroring brands/official/ (SVG sources, brand-config.json, etc.), then running firefox-brand-generator <your-brand>.
• The top-level browser/branding/{moz.build, branding-common.mozbuild, docs/} files are not produced by this tool.

Configuration Format

The main configuration file defines a list of transformations that specify how source assets are processed into output files. Each transformation has a type field and specific arguments based on the transformation type.

Source files can come from two locations: a shared "static" folder containing assets used across all brands, or brand-specific "source" folders containing assets unique to each Firefox distribution.

Transformation Types

• raster - Converts vector graphics or images to raster formats

  • fileType: Source asset location ("source" or "static")
  • inputPath: Source file path
  • outputPath: Output file path
  • outputFileType: Target format ("png", "jpg", "bmp", "tiff", "gif")
  • width: Output width in pixels
  • height: Output height in pixels
  • paddingPixelsWidth: Optional horizontal padding in pixels
  • paddingPixelsHeight: Optional vertical padding in pixels
  • offsetX: Optional horizontal offset in pixels
  • offsetY: Optional vertical offset in pixels
  • fit: Scaling strategy ("fill", "cover", "contain", "scale-down") - defaults to "contain"

• ico - Creates Windows ICO files with multiple sizes

  • fileType: Source asset location ("source" or "static")
  • inputPath: Source file path
  • outputPath: Output ICO file path
  • sizes: Array of icon sizes to include (e.g., [256, 48, 32, 16])

• icns - Creates macOS ICNS files with multiple sizes

  • fileType: Source asset location ("source" or "static")
  • inputPath: Source file path
  • outputPath: Output ICNS file path
  • sizes: Array of icon sizes to include (e.g., [1024, 512, 256, 128, 32, 16])

• copy - Direct file copy without modification

  • fileType: Source asset location ("source" or "static")
  • inputPath: Source file path
  • outputPath: Destination file path

• copy-preprocess - File copy with template variable substitution

  • fileType: Source asset location ("source" or "static")
  • inputPath: Source file path
  • outputPath: Destination file path

• assets-car - Creates macOS Assets.car bundle

  • liquidGlassIconFileType: Source asset location for liquid glass icon ("source" or "static")
  • liquidGlassIconPath: Liquid glass icon path
  • outputPath: Assets.car output path
  • appIconInput: Application icon source path
  • appIconFileType: Source asset location for app icon ("source" or "static")
  • iconInput: Generic icon source path
  • iconFileType: Source asset location for icon ("source" or "static")

• ds-store - Generates macOS .DS_Store files for disk images

  • outputPath: .DS_Store output path
  • appName*: Application name for the volume
  • volumeName*: Disk image volume name
  • backgroundImage: DMG background image path
  • backgroundImageFileType: Source asset location for background ("source" or "static")
  • volumeIcon: Volume icon file path
  • volumeIconFileType: Source asset location for volume icon ("source" or "static")
  • windowPosition*: DMG window position as "x y" (e.g., "200 120")
  • windowSize*: DMG window size as "width height" (e.g., "680 400")
  • appIconPosition*: App icon position as "x y" (e.g., "209 220")
  • appDropLinkPosition*: Applications link position as "x y" (e.g., "472 220")

Note: Fields marked with an asterisk (*) support string substitution using template variables from the brand configuration.

Brand Configuration

Brand configurations are stored in brand-config.json files within each brand folder. They contain:

• strings - Key-value pairs for template substitution (e.g., product names, version strings)
• env - Environment variables for build configuration

Template Processing

The copy-preprocess transformation supports template variable substitution and conditional logic:

String Substitution

• {{#str key}} - Replaces with value from strings in brand config
• Example: {{#str brandName}} → Firefox

Conditional Blocks

• {{#if condition}} - Start conditional block
• {{#elseif condition}} - Alternative condition
• {{#else}} - Fallback block
• {{#endif}} - End conditional block

Supported Conditions

• Equality: env == value or env != value
• Logical AND: condition1 && condition2
• Logical OR: condition1 || condition2
• Parentheses: (condition1 || condition2) && (condition3)

Examples

{{#if name != official && name != aurora}}
Official or aurora build content here
{{#elseif name == nightly}}
Nightly build content
{{#else}}
Other build content
{{#endif}}

macOS-Specific Operations

These transformations require macOS-specific tools and only work on macOS systems:

• ICNS Generation: Creates multi-resolution icon bundles using Apple's iconutil command-line tool.

  The process generates a temporary .iconset directory with PNG files at various sizes (including @2x retina variants for standard sizes like 32, 64, 256, 512, 1024), then uses iconutil -c icns to compile them into a single .icns file.

• Assets.car Creation: Generates compiled asset catalogs using Apple's actool (Asset Catalog Tool).

  The process creates a temporary .xcassets bundle containing AppIcon.appiconset (with sizes 16-512px at 1x and 2x scales) and Icon.iconset (256px variants), along with a liquid glass icon template directory.

  actool then compiles these into an optimized .car file. This file is specifically used on newer macOS versions for the App icon, particularly for rendering the liquid glass icon effect.

• DS_Store Generation: Creates properly formatted .DS_Store files for disk images by generating a temporary DMG using the create-dmg script, then extracting the .DS_Store file from the mounted volume.

  The process includes setting background images with sips (to adjust DPI), creating volume icons via ICNS generation, and positioning UI elements.