Icon shapes and masking

[owencm]

I've been thinking about how Vanilla Android 7 has largely round icons (or at least some new Google-flavor Android does) and thus icons provided in the manifest, even with the platform property will look slightly strange on that OS.

I heard some developer complain recently that they're not sure how to get the circular shape.

Taking a broader view on this problem, Samsung has their own icon mask shape, Xiaomi have their own icon shape etc.

Thus I wonder if a better solution is to have sites provide their icon as a large square with sufficient padding around the edges and then have the browser apply a mask appropriate for the OS it's running on.

Not sure how that could fit into the spec in terms of platform etc. Perhaps we could just use platform: 'android_maskable' or something, but wanted to raise it as an idea.

[kenchris]

I will try getting some designer feedback whether such a solution would be satisfactory. My fear is that branding is very important to businesses and designers spend considerable time on getting each icon perfect, which can even include polishing on pixel level.

I also don't know for businesses what matters the most, a perfect looking icon which might not necessarily fit 100% with the phone theme, or fitting in. I would guess that the former is what really matters and where the focus will be spend. After that I can see businesses creating alternative forms for major platforms they care about.

I could see my imaginary company creating a brand icon, then optimizing it for iOS and stock Android. Then later making a round version for Pixel and maybe one for Samsung depending on my market...

I think rather than trying to make the implementation do the masking, people might prefer to use online tools for that and then either use the result or redo it.

Something like: https://romannurik.github.io/AndroidAssetStudio/icons-launcher.html#foreground.type=clipart&foreground.clipart=android&foreground.space.trim=1&foreground.space.pad=0.25&foreColor=rgba(96%2C%20125%2C%20139%2C%200)&backColor=rgb(68%2C%20138%2C%20255)&crop=0&backgroundShape=square&effects=none&name=ic_launcher

I will reach out to some of our designers to get their feedback :-)

[marcoscaceres]

I still think @pornel's suggestion of targeting "os styles" is best and makes most sense here.

[kenchris]

Android currently has "android:icon" and "android:roundIcon" as resources.

When a launcher requests an app icon, the framework returns either android:icon or android:roundIcon, depending on the device build configuration.

I am not even sure if developers can create special icons for the samsung launcher, but if they can they probably have an entry like that, say "samsung:icon" or similar.

The round icons on Android are roundish and not actually always 100% round, just check Allo and Duo icons.

Also, the icons can be vastly different when round and cannot be created with just a filter:

I think that Android should just support

"platform": "android:icon"
"platform": "android:roundIcon"

As Android (or versions of Android like Samsung) can add new values in the Android system itself, that would probably be flexible enough.

Also, keep in mind that Pixel phones don't enforce that all icons are round and will fall back to "android:icon" as these icons will look much better than a not optimized round icon.

[clagom]

Hello, @kenchris told me about this topic, so I’m here to give an opinion from a designer point of view. I think Kenneth highlighted a crucial matter talking about the importance of a brand, and how it is displayed with the icon.
An integrated automatic tool that applies the right shape according to the style of the OS can surely be useful especially on the consumer level, but would be good to also give the possibility to provide different and customised icons according to the platform. Applying shapes as a cropping should on the contrary be avoided for the same branding reasons, risking to cut off part of the logo/icon.

On this image we can see how at Google are basically redesigning the icons to be circles, rather than applying the shape (gmail is the easiest integration among these).

[kenchris]

I just talked to Erik Hellman, one of the Android GDEs and Android book author, and he knows of no cases where vendors like Samsung, Xiaomi and Huawei have made it possible for developers to ship icons optimized for their launcher icon style, the only currently known forms are "android:icon" and "android:roundIcon"

[mhartington]

Hi there! Just want to add my opinion on the subject.
I'd be all for having an option to enable some sort of OS level icon clipping.

I'd push for having it be a default opt-in for a round icon. Coming from some native ios development, it's a nice feature to not have to worry about, and I'd assume most devs would want the round clipping. For those who do not want clipping, they could just set that.

[RobDolinMS]

Thinking about PWA developers (and literally hundreds of Manifest files I've looked at), I think there are likely to be two primary cases:

• Basic - PWA developer just wants to link to a single image (or a few sizes of the same image) from their Manifest and have the Manifest consumers adjust (resize, crop, round, etc.) as appropriate
• Custom - PWA developer would like to include multiple image assets in their Manifest so their end users have the nicest/richest experience on their devices. This might include designating different images for different platforms.

[kenchris]

I think that /basic/ is probably more due to the lack of access to a graphics designer, so just doing the bare minimum as well as doable. I have falling into this category myself :-) That said, I could see someone here allow the UA to apply filters etc, but it should probably be opt in and I am not convinced that this is better than having people use services, like say pwabuilder.com to generate such icons from what is already in the manifest.

What I am concerned about here, is to allow users to include images and hints such that they can provide the experience they believe their users need, ie. look good on Windows and on Android, and look even better integrated with round icons on Android launchers using that (ie Pixel and Nokia phones so far).

In order to get this rolling, I suggest that we add the "platform" hint to images, and my suggestion for Chrome on android would be to support any value starting with "android" as optimized for Android. And using "android:roundIcons" to indicate Android icons optimized for the Pixel launcher etc.

I don't know what Microsoft is planning as there is some rumors of a Windows UX redesign, but maybe the value "windows" could be a good starting point.

If we can agree on this, we might be able to get implementation going and I can add this to the spec, incl examples.

I think we can look at whether to support masks as an opt in, as a separate feature.

The other question here related to splash screens and there is a PR open for that. Should we support a hint like "platform": "splashscreen" as well, or only go with a "splashcreens" entry like "icons".

[kenchris]

https://developer.android.com/preview/features/adaptive-icons.html
https://docs.microsoft.com/en-us/windows/uwp/controls-and-patterns/tiles-and-notifications-app-assets

So looked at what Windows and Android O now does. The adaptive idea with two images would work well, especially for Windows as well, if you think about full-bleed branded tiles which has to have a margin of 1/6 of the size (which is the same for adaptive icons, yay!)

Example text:

Adaptive icons are icons which are prepared to support masks and animations. Each icon consists of two similarly sized square images. A foreground image, which can be considered the main icon, and a background image, which may and may not be used given the platform.

The inner 2/3 of the images appears within the mask. Thus, that part is what makes up the final image, i.e. by default there will be a margin of 1/6 of the size.

For special animations, each layer may move up to 1/3 of the icon size in each of the directions.

In order to use adaptive images, you define "foreground" and "background" properties of icon objects. A "src" can be added in order as a fallback for vendors which do not support adaptive images.

  "icons": [
      {
        "foreground": "icon/fg.png",
        “background”: “icon/bg.png”,
        “src”: “icon/fallback.png”, 
        "sizes": "432x432",
        "type": "image/png"
      }
   ]

On Windows 10, a full-bleed tile can be generated from an adaptive image by ignoring the background and using only the foreground image.

The default Android sizes are 108px, 216px, 324px and 432px for 1 to 4dp respectively. For Windows, that is 96px, 192px, 288px, and 384px, so the Android sizes should work fine on Windows when scaled a bit down, though developers can add these extra sizes to get super clear unscaled images.

iOS has a few masks with rounded corners (the size of the rounded corner differs from iPad and iPhone for some reason) but applying such filters to the adaptive icons.

iOS supports 1dp and 2dp as far as I can tell, with the following sizes:

57px (iPhone)+72px(iPad) at 1dp
114px+144px at 2dp

Applying such a mask (covering 2/3 of the icon size) and scaling to those sizes should still provide quite clear images. Example, using 216 from above (2dp Android adaptive)

216px / 3 * 2 = 144px which is the iPad 2dp size!

If people want to use SVG for background (as that could make sense) and reuse that for all icons, just do

  "icons": [
      {
        "foreground": "icon/fg@4.png",
        "sizes": "432x432",
        "type": "image/png"
      },
      {
        "foreground": "icon/fg@2.png",
        "sizes": "216x216",
        "type": "image/png"
      },
      {
        "foreground": "icon/fg.png",
        "sizes": "108x108",
        "type": "image/png"
      },
      {
        "background": "icon/shared-bg.svg",
        "sizes": "any",
        "type": "image/svg"
      },
   ]

[clagom]

Some examples of Adaptive icons, and a small guideline to display the proportions needed to be inside of the Android cropping masks.

Single images:

The grid

Example on Windows phone

Animated gif

[mgiuca]

I did a review pass on #657. But @dominickng and I also had a long chat about the high-level strategy here and the details of the dimensions.

Note that the original proposal on this bug was to simply introduce a platform-specific icon purpose, which lets you say "this is my Android icon", "this is my Windows icon", etc. That's contrasted to the approach @kenchris takes in #657 which is to define a contract between the developer and user agent which we can attempt to fulfill on all platforms. This latter approach is a lot more "webby" but it has some issues which I'll get to.

First, to the dimensions. I took @clagom's diagrams and extended them. In @kenchris's PR, he's proposing that we specify the safe zone as 4/5 (the diameter of the safe-zone circle as a percentage of the width of the source square). Remember that I previously stated that the Android safe zone is 22/36. I'll get into why that's important. Let's consider two options and how they render on Android:

OPTION A: We specify the safe zone as 22/36 (61%) diameter (roughly). This exactly fits Android's model of the safe zone. (To avoid this arbitrary seeming number, we could drop down to 3/5 or 60%. The key is that the safe zone is smaller or equal to Android's.)

Under this option, the website gives us this image, with the important contents exactly fitting inside a circle of radius 61%:

(As @clagom shows above, they would probably want to make the icon a little smaller so it has some padding, but I'm just going to keep everything tight for demonstration purposes.)

So under this policy, the user agent is allowed to crop exactly down to the safe zone, like this:

I'm not sure exactly what Android does, but the diagram suggests that it would cut down to a 72dp-diameter circle, leaving a bit more of a margin:

So this turns out OK on Android, but it kind of doesn't make sense unless you chop off a large area from the outside. If another platform just takes the icon and rounds off the corners, it's going to look much too small. So if we go with Option A, you pretty much have to cut off around 1/6 of the space on all sides.

OPTION B: We specify the safe zone as 4/5 (80%), as in #657. This is a pretty reasonable safe zone which will still look fine if you don't cut anything off.

Under this option, the website gives us this image, with the important contents exactly fitting inside a circle of radius 80%:

However, the web-specified safe zone is much bigger than what Android allows, which means if we just pass this image to Android, it MAY crop down to 61% of the image:

Oops. Though as above, Android is likely to only cut to 72dp, not 66dp, resulting in a bit more of the image:

Though still not great.

So Option B doesn't work on Android if we just pass the image through to the OS. However, what the user agent can do is automatically add a border of 15% on all sides:

(Shown here in black, though it could set it to the app's theme colour or the most common colour in the image, etc.)

Now if we give this to Android, it will correctly chop down to 61% or 66%, giving the correct tight icon shown above. However, the extended border may be visible to the user in certain extreme cases. I've never seen Android show any part of the background outside of the 72dp zone due to parallax, but who knows what a future version of Android might do. I think it's fairly safe to assume the user will never see these "black" pixels.

Basically, we get the same result either way, but Option A aligns the Web to Android, while Option B makes the user agent do work to align Android to the web. I daresay Option B is more palatable, because the Web shouldn't be designed around the quirks of one specific platform. It should be designed in the most generic way possible, and then user agents should do their best to map onto the underlying platform.

On Windows 10, the "full bleed" option (Halo logo in this example) roughly fits without having to manipulate the Option B image at all. (You're supposed to leave 16% margin on each side; Option B leaves 10%, but since it's in a circle, it's more like 22% on each side if you're fitting a square icon into the circle.) Anyway, this roughly fits the expectation.

However, we then considered trying to fit this into a square, which is particularly important on iOS.

On iOS, there's an expectation that icons will be cut into a rounded-square, not a circle, which means you don't have to avoid the corners that a circle would cut off. For square-shaped icons, this means you make the important part much bigger. Thus, an image designed to fit in Android's (or, the Web's) circle safe zone will look too small on iOS, or another device with a square mask:

This wastes cos²(45°) or 50% of the space.

For a real world example, we looked at the Facebook logo. Here's what the Facebook logo looks like inside the Option B icon metrics:

And here's what it looks like cropped with the 72dp outer ring, in both circle and rounded-square masks:

The top one is basically what this will look like on circle-masked Android devices, while the bottom is what it will look like on iOS. In the circle, the "f" comes a bit too close to the edge, and in the square, the "f" is a bit too small. You'd probably want to extend the bottom of the "f" all the way to the bottom so it doesn't cut off like that. And you'd probably want to shrink the "f" a bit more so it has more margin in the circle, which will make it even smaller in the square version.

Basically, @dominickng's point is that we should be giving developers a way to specify a different icon on each platform, designed with that platform in mind. That's OPTION C. However, a few counter-points:

• Android adaptive icons are also supposed to work as a square. Facebook already has the above issue on square-masked Android platforms. So while this isn't ideal on iOS, it's a minor imperfection which is the cost of using the generalized Web platform.
• Tailoring things for each platform isn't something we generally build into the Web platform. I prefer if we can describe a generic solution and then have user agents worry about platform-specific details. Since we have a pretty good general solution here, I'd not be a fan of us giving up on this and telling developers to specify "one normal icon, then if you want, an Android adaptive icon, a Windows 10 tile icon and an iOS home screen icon."
• Developers who really want to supply an iOS-specific icon can user-agent detect in the Manifest and provide a special icon set on that platform.
• The downsides of Option C are the same as always on the web: the most popular platforms will enjoy tailored icons, while less popular platforms will have no developers looking at them. What if, for example, Chrome OS switches to adaptive icons at some point (and I have no insider information on this, just hypothetical) — would we just use the "android" icons there? Or would we introduce a new platform which developers have to tailor their icons for?

My preferred option is still Option B, which is #657, with those proposed dimensions (4/5). But there's a lot to consider. I hope this has been helpful.

In summary, I spent most of today literally trying to fit a square peg in a round hole.

[kenchris]

My preferred option is Option B as I am not a fan of Option C.

The reason is that developers already complain that they have to define too many icons - which means that this might mean that they just end up defining an icon for say "ios" and thus ignore generic icon and thus, the icon will look worse on Android and Windows that today.

That is a real fear. PMs might say that one platform is what has top priority and the rest is an afterthought.

[dominickng]

I agree that Option C has a lot of downsides, but it may be the most pragmatic way forward. :(

My worry about Option B is that we enshrine non-optimal icons for platforms that don't use a circular safe zone. Additionally, correct branding is certainly something that many site owners will want pixel-perfect control over, which will not be the case if we have to add or subtract pixels on different platforms. Matt has already mentioned iOS squircles, but Windows is also different.

More generally, some of the challenges with Option C can be mitigated, e.g. by specifying that the platform-specific icons are optional, and that the presence of a generic icon required for us to consider using any platform-specific one.

The whole point of this feature is to allow developers to supply a platform-specific icon, and wrapping some genericity into the feature seems counter to the original goal. We'd have to try and solve this problem again for platforms which introduce or use different semantics .

[kenchris]

I don't agree.

I bet that you will see devs adding special icons for iOS and totally ignoring Windows and maybe even Android, or just giving it a default square icon like today, which Windows still might have to modify.

Also, this is the web platform, and we would love people to create new product groups and reuse flexible primitives. There is no reason why, say a TV manufacturer wouldn't like to support PWAs and be to able to apply a nice mask and get squircle icons instead of being forced to use square icons like today. Option B gives everyone this flexibility - to get something that looks integrated with the their platform, while still allowing developers to have quite some control over the look.

If you want pixel perfect look for each platform, then that won't be the perfect solution, but the web is about the long tail and not just the big brands who will be the ones caring most about this and having the resources to optimize for every single platform out there.

And as Matt said, you can still do UA sniffing and supply platform pixel perfect icons to that specific platform.

The whole point of this feature is to allow developers to supply a platform-specific icon

Not entirely. It is also supporting platforms, such as Android, that uses masks and might even be able to change the mask at runtime. Though Windows doesn't use masks, it does add padding to a lot of icons, if you read their guidelines.

--

One more real example: Samsung has a platform called Tizen, and they even ship phones with that in select markets. As that is based on the W3C Widget spec, let's pretend they want to move that to PWA.

The default icons on Tizen phone are round, so the current icon support will make the apps look alien on the system, eg. not round. Getting developers to supply "tizen" icons would probably be a lost cause due to it being an emerging platform with little uptake so far, so some kind of generic maskable support would definitely help here.

[mgiuca]

@dominickng, @kenchris and I had a half-hour VC about this and came to a rough consensus for Option B. Meeting notes follow:

• Ken/Matt: Worried about small players (e.g., new operating systems in the future) unable to enter the market to convince devs to add their platform-specific icons (under Option C). End up using iOS or Android icons, essentially ending up with apple-touch-icons all over again (or "vendor prefixing" used outside of the original vendor).
• Dom: Already have a default icon.
• Ken: Default icon is not good enough as a generic thing. Everybody wants a maskable icon of some kind. In the future we could add iOS specific icon in the future for top-tier polish.
• Dom: Same argument would apply then. If we're going to add platform-specific icons in the future, why not just do it now?
• Dom: Exposing the capability to map your icon to platform-specific form, but requiring transform.
• Dom: If only developers who really care are providing the maskable icon, then this is a fine-tuning/tweaking capability, not for widespread use.
• Matt: This isn't just for top 1% of developers; ideally this is accessible to all developers.
• Ken: Developer tools (or Lighthouse, etc) can show you how your maskable icon will look on various major platforms. [Good idea: we should talk to Chrome devtools and/or Lighthouse.]
• Dom: We should therefore push developers to maskable icons.
• Matt: We should give equal weight to both the traditional and maskable icons (both are equally valid, depends on the brand; e.g. Gmail is a top-tier app that just doesn't make sense to have a maskable icon).
• Dom: Option B takes control away from developers.
• Matt: Giving control also means maintenance burden. If the underlying platform changes, we want developers protected from underlying platform changes in the future, not having to update their site every time Android changes, for example.
• Dom: If we go with Option B, we would want non-normative text explaining the nuances, e.g., the border we would be injecting into the icon.
• Vague resolution: Proceed with Ken's Add a 'masking' purpose, for allowing the UA to supercompose such icons #657 (Option B). Matt and Dom to look over and suggest non-normative text that highlights some of the nuances of this discussion.

Thanks everybody!

[marcoscaceres]

Happy for you all the take the lead on this until I can re-engage from the Mozilla side.

[ithinkihaveacat]

Has there been any discussion/thought about how manifest/homescreen icons might interact with notification icons? This is another area where the web bumps up against system/OS expectations and conventions.

I believe native apps on all platforms use exactly the same base icon for the homescreen and in notifications, and so it would be useful to be able to specify this just once. (Relevant section of the notification spec; related issue.)

[dominickng]

@ithinkihaveacat that seems to be an orthogonal issue to this one, so perhaps it's best to open a new issue to discuss that.

[mgiuca]

Closed by #657.

[codercatdev]

Sorry I have read through the thread three times, and I am still missing it. Does someone have a working repo or manifest.json they could share? So that my PWA looks normal.

[JacobDB]

@Ajonp I don't think it's been implemented in any current browsers yet, so you won't be able to get it working currently.

[codercatdev]

@JacobDB gotcha I saw the Merged and made some assumptions. I will continue down the Trusted Web Activities route for it then to get into the Play Store as well. Thanks for the feedback!
https://developers.google.com/web/updates/2019/02/using-twa

[cor3000]

just in case someone spends time searching a solution and ending up here ...
the helpful documentation is
https://w3c.github.io/manifest/#icon-masks

this worked on my side: after adding the "purpose": "maskable"

    "icons": [
        {
            "src": "/img/myappicon.png",
            "type": "image/png",
            "sizes": "48x48 72x72 96x96 144x144 192x192 512x512",
            "purpose": "maskable"
        }
    ]

[adamreisnz]

Does this also create support for adaptive icons for PWA's?

[cor3000]

Not as far as I understand it. Adaptive icons have 2 layers, maskable icons only 1 layer with enough padding to cut out any common shape.

[adamreisnz]

That's a shame, is any provision being considered for adaptive icons?

I've searched far and wide, but there appear to be precisely 0 resources on how to create adaptive icons for PWA's. Looks like it's simply not possibly at the moment?

[dominickng]

We deliberately did not encompass the 2 layer Android adaptive icon spec here since it’s specific to Android and has no real counterpart on other platforms. We try to avoid encoding platform-specific concepts in web platform specs.

The concept of a maskable icon is cross-platform, which is why we chose to take it into the spec.

[mgiuca]

Just to clarify this position: using maskable icons will (at least in Chrome) create an adaptive icon in Android, it just won't have the 2 layers. So it will be used everywhere in Android that adaptive icons are needed, and also work properly on other operating systems once they implement it.

We had a long discussion about the 2 layers thing and found that it was almost completely imperceptible even on Android. It's only noticeable when you are dragging an icon around on the home screen rapidly (the two layers parallax as you're dragging), but your finger is covering the icon so you have to look very carefully under your finger. Given this, we didn't see a reason to design and implement an Android-specific web API for something that almost nobody will ever notice.

However, there is significant cross-platform value in having a large icon that can be cut out into whatever shape the operating system wants, thus we settled on maskable icons for the web spec.

[JacobDB]

Maskable icons are now available in Chrome 79 https://developers.google.com/web/updates/2019/12/nic79#maskable-icons