Overview
Firefox users can express themselves by creating and/or installing colorful themes that apply to certain parts of the browser’s interface, found mostly within the chrome.
How theming works
Themes are extensions built with the WebExtensions API, which is a cross-browser technology that allows developers to change aspects of a browser's look and feel. Learn more about this API on MDN
The browser interfaces that can get themed:
- Panels
- The toolbox (Tab Strip, Navigation Toolbar, Address Bar)
- Find in Page Toolbar
- Sidebar
- Address Bar
- New Tab and Firefox View
Light and dark theme
Firefox provides an official light and dark theme (not to be confused with mode) that can be added via about:addons.
Firefox light theme
Firefox dark theme
System (auto) theme
Firefox is set to a native theme by default. When no theme is set, the default takes colors and overall styles from the user’s operating system.
Firefox for Ubuntu
How to create a theme
In order to create a theme extension, you will need:
- A manifest.json file: The file for defining theme colors.
- (Optional) an image file in JPG, PNG, APNG, SVG, or GIF: A requirement for themes that use images.
Theme manifest
The manifest.json file contains theme metadata, such as the list of color properties that correspond to different parts of the browser UI. The available properties should be generic enough to be reused in different contexts if needed.
Not every surface and interactive state can be themed, therefore there are only a limited number of customizable properties available. For example, there is no way to assign a unique hover state color for a popup’s (panel) items, so the browser just generates that hover state’s color by mixing the current text color with some transparency.
Manifest example:
{
"name": "Light Blue Theme",
"version": "2.0",
"theme": {
"properties": {
"color_scheme": "light"
},
"colors": {
"button_background_active": "oklch(0.76 0.2 260)",
"icons": "oklch(0.34 0.14 260)",
"tab_background_text": "oklch(0.27 0.1 260)",
"tab_text": "oklch(0.27 0.1 260)",
"tab_selected": "oklch(0.97 0.05 260)",
"tab_line": "oklch(0.34 0.14 260)",
"tab_loading": "oklch(0.27 0.1 260)",
"frame": "oklch(0.83 0.17 260)",
"frame_inactive": "oklch(0.76 0.2 260)",
"popup": "oklch(0.97 0.05 260)",
"popup_text": "oklch(0.27 0.1 260)",
"popup_border": "oklch(0.76 0.2 260)",
"popup_highlight": "oklch(0.83 0.17 260)",
"popup_highlight_text": "oklch(0.27 0.1 260)",
"toolbar": "oklch(90% 0.130 260)",
"toolbar_text": "oklch(0.27 0.1 260)",
"toolbar_field": "white",
"toolbar_field_text": "oklch(0.34 0.14 260)",
"toolbar_field_focus": "white",
"toolbar_field_border": "oklch(0.69 0.22 260)",
"toolbar_field_border_focus": "oklch(0.55 0.240 260)",
"toolbar_top_separator": "transparent",
"toolbar_bottom_separator": "oklch(0.76 0.200 260)",
"ntp_background": "oklch(0.90 0.130 260)",
"ntp_card_background": "oklch(0.97 0.05 260)",
"ntp_text": "oklch(0.27 0.1 260)",
"sidebar": "oklch(0.97 0.05 260)",
"sidebar_border": "oklch(0.62 0.24 260)",
"sidebar_text": "oklch(0.27 0.1 260)",
"sidebar_highlight": "oklch(0.83 0.17 260)",
"icons_attention": "oklch(0.34 0.14 260)",
"toolbar_vertical_separator": "oklch(0.69 0.220 260)"
}
}
}
|
Name |
Description |
|---|---|
|
name |
Theme name |
|
theme |
Object made up of colors, images, and properties |
|
version |
Manifest version (use 2.0 or higher) |
Theme
|
Key/object |
Description |
|---|---|
|
colors |
The colors object contains the color properties for theming. |
|
images |
An object for handling images is made up of theme_frame and additional_backgrounds |
|
properties |
An object for handling color_scheme |
Images
Must be included alongside the manifest and not refer to an outside URL.
|
Key/object |
Description |
|---|---|
|
additional_backgrounds (EXPERIMENTAL) |
Optional array of URL strings for additional images to be included behind theme_frame |
|
theme_frame |
The image URL that is anchored to the top corner of the toolbox. Can take up both the Tab Strip and Toolbar if Toolbar is transparent |
Properties
|
Key/object |
Description |
|---|---|
|
additional_backgrounds_alignment |
An optional array of values that define the alignment of the corresponding items of additional_backgrounds (see Images). Defaults to "right top". Accepts: "bottom", “center", "left", "right", "top", and combinations like "center bottom", "center center", "center top", "left bottom", "left center", "left top", "right bottom", "right center", "right top" |
|
additional_backgrounds_tiling |
An optional array corresponding to how"additional_backgrounds" items repeat: "no-repeat" (default), "repeat", "repeat-x", "repeat-y" |
|
color_scheme |
Optional color scheme for the chrome and in-content pages. Defaults to "auto" (based off the theme). Accepts: "light", "dark", "system" (based off the operating system) |
|
content_color_scheme |
Optional color scheme to in-content pages, accepts same values as color_scheme above |
Colors
Please refer to comprehensive guidance under the Colors tab.
How to craft an attractive AND accessible theme
On contrast
Learn more about WCAG’s contrast minimum guidance
Avoid background colors that don't have enough contrast with text colors. WCAG recommends at least a 4.5:1 contrast for regular text sizes (below 18pt or 14pt bold)
Avoid background colors that don't have enough contrast with UI graphic elements (e.g. borders, icons). WCAG recommends at least 3:1 contrast.
Panels
Panel (popup) and panel text (popup_text)
Make sure popup has enough contrast with popup_text, sidebar_text.
The hover state of panel list items and buttons rely on the text color mixed with some transparency. Make sure this state also contrasts well against popup.
Panel border (popup_border)
The toolbox
Composed of the Tabstrip and the navigation Toolbar.
Tab Strip (Tabs Toolbar)
Tab strip in horizontal tabs mode
Uses the frame key for its background, which should have enough contrast with tab_background_text, icons, tab_text, toolbar_field and toolbar_field_border.
The hover and active state of Toolbar Buttons fallback to a transparency mix with icons, so make sure those states also have enough contrast.
Navigation Toolbar
Uses toolbar for its background, but changes to frame in vertical tabs mode.
Navigation toolbar in vertical tabs mode
Navigation toolbar in horizontal tabs mode
Address Bar
Uses toolbar_field for its background, toolbar_field_text for its text, toolbar_field_border for its border, toolbar_field_border_focus for its focus outline.
toolbar_field needs enough contrast with toolbar_field_text, icons, and popup_highlight. popup_highlight needs enough contrast with popup_highlight_text.
Once again, a mix of transparency with the text color - in this case toolbar_field_text, is used for hover states, so make sure those contrast well with toolbar_field.
Find in Page
Uses the toolbar for its background, so make sure toolbar_text, toolbar_field_border, and toolbar_field_border_focus contrast well with that.
Just like the Address Bar, guarantee enough contrast between toolbar_field andtoolbar_field_text.
Sidebar
In non-vertical tabs, the Sidebar’s background uses toolbar, but in vertical tabs mode it switches to the frame color. Make sure both those colors have enough contrast with icons, toolbar_text, bookmark_text, sidebar_text.
Any panels that open within the Sidebar use popup for its background color, so sidebar_text should contrast well with that.
How the operating system’s accent color plays a role within a theme
When you install a theme, inputs (e.g., button, checkbox, toggle) within the chrome are themed (colored) after the operating system’s accent color.
Below, an example of the AI chatbot on the sidebar with a green theme installed. Inputs and links still make use of the OS accent color, in this case Ubuntu’s orange.
