I'm working on bringing my Safari extensions StopTheMadness and Tweaks for Twitter from Mac to iOS, and it's progressing well! During this process I've noticed that there are some platform-specific differences between Safari iOS and Safari Mac extensions, as indeed there are between Safari Mac extensions and Google Chrome extensions, even though they all use the same cross-platform Web Extension format. (There's an older Mac-specific Safari app extension format, but that won't be available on iOS.) One easily noticeable platform-specific difference is the extension icons. Safari unfortunately tends to eschew the use of color now: you can see that all of Safari's built-in toolbar items are grayscale. If you're porting your Chrome extension to Safari Mac, you may notice that your toolbar item suddenly seems out of place and conspicuous; it's almost like landing in Kansas after having been to the land of Oz. Ironically, the Safari toolbar itself gets color in macOS Monterey, but not the toolbar items.
Apple's developer documentation for Safari web extensions has a section about icons, but it appears not to have been updated for Safari extensions on iOS. I filed a Feedback (FB9207164) requesting that Apple update the documentation, but Apple inexplicably requested that I "Please capture a screen recording of the issue reproducing. Also, please provide a sample project, or sysdiagnose captured immediately after the issue occurs along with a relevant timestamp for closer examination." For documentation feedback! So that was less than helpful. And without proper documentation, the only rational option is to give up. Thank you for reading my blog post, and sorry for wasting your time.
Wait, I just remembered that I'm irrational! Of course I'm going to reverse engineer the thing. As an experiment, I programmatically generated a bunch of extension icons of every conceivable size. In order to distinguish them visually, each icon was a numerical representation of the icon's size. Then I added all of the icons to my Safari extension's manifest.json file to see which icons Safari would pick when given the choice. In the Preferences window of Safari Mac, the Extensions pane uses the icons list from the manifest, showing the 96x96 icon on retina screens and the 48x48 icon on non-retina screens. The Websites pane shows the 64x64 icon on both retina and non-retina. The toolbar of a Safari window, in contrast, uses the default_icon list of the browser_action in the manifest. On macOS Big Sur, the toolbar shows the 38x38 retina and 19x19 non-retina icon sizes, while on macOS Mojave, the toolbar shows the 32x32 retina and 16x16 non-retina icon sizes. I believe that these sizes are determined by Safari's toolbarItemIdealPointSize private method. This is mostly in line with the developer documentation, which recommends providing 16-, 19-, 32-, and 38-pixel sizes for the toolbar and 48-, 64-, 96-, 128-, 256-, and 512-pixel sizes for Safari Preferences. I haven't seen any usage of the 128, 256, or 512 sizes, though.
Safari Mac extension icons are similar to but not exactly the same as Chrome extension icons. According to Google's documentation, "Extensions should also provide a 48x48 icon, which is used in the extensions management page". This is the same as in Safari Extensions Preferences, except for the retina difference. In the toolbar, "The browser action icons in Chrome are 16 dips (device-independent pixels) wide and high." This is also the same as in Safari on Mojave. However, the move to slightly larger 19/38 icons in more recent macOS versions is not matched by Chrome as far as I know.
The icon situation looks a lot different in Safari iOS, at least with the current beta version. The iOS Settings app doesn't use the icons from the Safari extension, it uses the icons from the native iOS app that serves as a container for the Safari extension. Safari iOS itself, like the Safari Mac toolbar, uses the default_icon list, but it shows the 48x48 icon size, or the 144x144 size on devices with a @3x display. Curiously, it doesn't seem to use the 96x96 size on retina displays. One caveat is that I only have one physical iPad to test with, so most of my testing was with the iOS simulator in Xcode. In any case, the behavior of Safari iOS clearly doesn't match the developer documentation.
I'll end my analysis by returning to a discussion of color. The icon of an active Safari iOS extension appears inside in the address bar on iPad, though not on iPhone, presumably because iPhone has less space. In both cases, the extension icon appears in the popup menu of the grayscale "action" widget in the address bar. Of course, this is all assuming the controversial new design of the Safari address bar in the iOS 15 beta. Whether the new design survives until September is an open question, since so many people have openly questioned the new design. I won't debate that here. The question at hand is whether Apple intends Safari iOS extension icons to be grayscale like in Safari Mac or full color like in Chrome. I suspect the answer is grayscale, because again a full color icon would tend to look conspicuous to the user in Safari, at least on iPad. It should be noted nonetheless that it's definitely possible to have a full color extension icon in Safari on both iOS and Mac. My own extension Tweaks for Twitter has a (light) blue color in Safari Mac when it's active, i.e., when you have twitter.com open. (A few people have been put off by the color, but the Tweaks toolbar icon isn't used except to set the preferences, so the item can just be removed from the toolbar if it proves distracting.)
You might be wondering, aren't all Safari extensions blue in Safari? No, actually, Safari uses your highlight color in System Preferences to highlight extension icons, indicating that the extension is active on the web page. If you change your system highlight color to, say, purple, then Safari extensions will also be highlighted purple. The trick is that the highlight color is only applied to "template" images, which are essentially black icons with a transparent background. If your extension is not black — if it's blue, for example, like Tweaks for Twitter — then Safari doesn't recognize the image as a template and won't apply the highlight color. I've heard that some extension developers apply a little color to their extension icons to make them not quite black and thus not quite templates, thereby avoiding the annoying highlight. Certainly a lot of Safari users have complained that their extensions are all blue. Another controversial decision by the Safari team. On iPad, I'm not aware of a way to remove the extension icon from the address bar, or a system setting to change the highlight color, so if a user is bothered by the color of your icon, there's no recourse. Thus, grayscale may be the safest option for developers on iOS.
I hope that this blog post has been somewhat useful to developers in porting their extensions to Safari. And I hope that the Safari team themselves will get the point and document this adequately. Or at least point their documentation at this blog post!
The situation today is mostly the same as I described above in 2021. I do have a few little details to add now.