A browser extension needs more than one attractive icon. This guide explains how to plan manifest icons, toolbar sizes, and store artwork across Chrome, Firefox, Edge, and Safari, with a reusable asset checklist for design, development, testing, and submission.
Overview
Extension icons appear in several contexts: the browser toolbar, extension management screens, menus, bookmarks, installation dialogs, and marketplace listings. Each context may display the same brand mark at a different size, against a different background, and with different expectations for transparency or promotional artwork.
The safest workflow is to create a master icon first, then export a deliberate set of raster assets rather than resizing one small image repeatedly. A square canvas, strong silhouette, limited detail, and clear contrast usually perform better at tiny sizes than a complex logo or wordmark. Treat the extension icon as a compact piece of visual identity, similar to a favicon, but do not assume that a website favicon file automatically satisfies every extension or store requirement.
Platform specifications change, and store submission screens can introduce requirements that are separate from the manifest. Use the inventory below as a planning baseline, then confirm the current documentation and submission interface for each browser you support.
Browser comparison at a glance
| Browser | Manifest or package role | Icon planning baseline | Store or listing consideration |
|---|---|---|---|
| Chrome | Declare extension icons in the manifest and reference toolbar or action icons through the appropriate extension configuration. | Prepare a small, medium, and large square set, commonly including 16, 32, 48, and 128 pixel exports. | Plan a listing icon separately from promotional screenshots or feature graphics. |
| Firefox | Define extension icons in the WebExtension manifest; browser-specific settings may be needed for Firefox behavior. | Use a comparable multi-size set and test the icon in the toolbar, add-ons interface, and installation flow. | Review the current add-on submission requirements for listing images and branding. |
| Edge | Chromium-based extensions generally use a Chromium-style manifest structure, but store submission remains a separate step. | Reuse compatible square exports only after checking rendering and naming in the Edge workflow. | Confirm current marketplace artwork dimensions, file limits, and review requirements before uploading. |
| Safari | Safari Web Extensions are packaged through Apple’s tooling and distribution workflow; the exact project structure differs from a direct Chrome upload. | Prepare high-quality square source artwork and export the sizes required by the Safari project and distribution process. | Account for Apple platform artwork, screenshots, metadata, and any app-distribution requirements that apply to the extension. |
This table is a planning aid, not a substitute for platform documentation. Browser support, manifest versions, store fields, and accepted formats can change independently of one another.
Checklist by scenario
For a new extension
- Create a master icon in a square, lossless format, preferably with enough resolution to support every planned export.
- Design a simplified small-size version if the primary mark becomes unclear below approximately 32 pixels.
- Export a baseline set such as 16x16, 32x32, 48x48, and 128x128 pixels. Add larger source files when a store or packaging workflow requests them.
- Choose PNG for transparent raster artwork unless a specific platform or tool requires another format. Keep the editable source separately.
- Use predictable filenames, such as
icon-16.png,icon-32.png,icon-48.png, andicon-128.png. - Map each file to the correct manifest field and verify that paths are relative to the extension package.
- Prepare a separate store icon, screenshots, and promotional artwork instead of stretching the toolbar icon into every listing slot.
For a cross-browser release
- Keep one canonical brand system, but allow platform-specific exports where packaging or store requirements differ.
- Compare manifest keys, action or browser-action configuration, and icon paths across builds rather than assuming that one manifest can be copied unchanged.
- Open the packaged extension in each target browser and inspect the toolbar, extension manager, installation prompt, and any pinned or overflow menu location.
- Check that build tooling has not removed, renamed, or compressed icon files unexpectedly.
- Record the browser version, package version, asset filenames, and store artwork revision in the release checklist.
For a rebrand or icon refresh
- Keep the new mark recognizable at 16 and 32 pixels before replacing the old assets.
- Update manifest references, package files, store listings, documentation screenshots, and promotional graphics together.
- Expect cached or previously installed assets to make the change appear inconsistently during testing. Remove and reinstall the extension where appropriate, and test a clean package.
- Maintain a short migration note so support teams can distinguish a deliberate redesign from a counterfeit or corrupted icon.
For a broader website and extension identity system, see the multi-site favicon system guide. The same principle applies: define a controlled asset family rather than creating unrelated icons for every surface.
What to double-check
Manifest references
A minimal Chromium-style example might look like this:
{
"manifest_version": 3,
"name": "Example Extension",
"version": "1.0.0",
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "icons/icon-16.png",
"32": "icons/icon-32.png",
"48": "icons/icon-48.png"
}
},
"icons": {
"16": "icons/icon-16.png",
"32": "icons/icon-32.png",
"48": "icons/icon-48.png",
"128": "icons/icon-128.png"
}
}
Use this as a structural illustration only. Manifest fields differ by browser, manifest version, and extension feature. Validate the exact schema for the target platform, and do not add fields simply because another browser accepts them.
Transparency, contrast, and shape
Inspect the icon on light, dark, and visually busy surfaces. Transparent edges can disappear against a similar background, while a white or black border can create an unintended box. Test both the original artwork and the browser-rendered result. A useful icon remains identifiable without relying on tiny lettering.
Accessibility and recognition deserve their own review. The favicon accessibility and brand recognition audit offers a useful framework for checking contrast, silhouette, and small-scale clarity.
Format and export quality
- Confirm the pixel dimensions rather than trusting a filename.
- Check for accidental indexed color, unwanted matte backgrounds, or excessive metadata.
- Open transparent PNGs against more than one background.
- Retain a lossless source and regenerate exports when the design changes.
- Use an ICO only where the target workflow explicitly calls for it; a website favicon format decision is not automatically an extension packaging decision.
Common mistakes
- Using one tiny file everywhere. Enlarging a 16-pixel image produces blur and jagged edges. Export from a larger source at each required size.
- Putting a wordmark in the toolbar icon. Text often becomes unreadable at small dimensions. Reserve the full wordmark for store artwork or screenshots.
- Confusing manifest icons with store artwork. A valid package icon does not guarantee that the marketplace listing has the correct promotional images, aspect ratios, or metadata.
- Copying a manifest between browsers without review. Similar WebExtension models do not mean identical fields, packaging, permissions, or store workflows.
- Testing only in the development folder. A packaged build can contain different paths or omitted files. Test the exact archive or project artifact submitted for release.
- Ignoring dark mode and high-density displays. Thin strokes and low contrast can disappear. Test the icon at native size and on more than one display setting.
- Skipping automated validation. Add checks for file existence, dimensions, transparency, and manifest paths before every release. The automated favicon CI checks guide provides a practical model for this workflow.
When to revisit
Review this checklist before the first public release, every browser-target expansion, each major redesign, and every store resubmission. It is also worth revisiting before seasonal planning cycles when several extensions or brands are updated together, and whenever build tools, manifest versions, packaging methods, or store interfaces change.
At minimum, make a recurring maintenance pass twice a year: verify official platform guidance, test a clean installation in supported browsers, and confirm that store artwork still matches the current product. Record what was checked and which browser versions were used so the next release does not depend on memory.
For the next release, create a small asset inventory with these columns: surface, filename, dimensions, format, transparency, manifest or store field, browser tested, and approval status. Then run this final sequence:
- Export the master artwork into the required sizes.
- Validate dimensions, format, transparency, and filenames.
- Check every manifest path against the packaged files.
- Install the package in each supported browser.
- Inspect toolbar, manager, installation, and listing contexts.
- Confirm store artwork and screenshots use the current brand.
- Save the tested package, checklist, and asset inventory with the release record.
For a broader browser and bookmark review, use the favicon testing checklist. A disciplined icon workflow reduces avoidable submission errors while keeping the extension’s visual identity consistent wherever users encounter it.