Add a 'masking' purpose, for allowing the UA to supercompose such icons

[kenchris]

Follow Matt's idea and just allow icons to be masked for now.

---

Preview | Diff

[kenchris]

I used the 11/36 @mgiuca stated in the old PR, but shouldn't this be 1/3 ? Where does this number come from?

[kenchris]

Also, as icons will most likely be squares, this would allow Windows to use icons with "masking" purpose and just not apply any masks @boyofgreen

[boyofgreen]

I do think this would be quite helpful. For example, the badge icon on windows is the same size as the smallest iOS icon, however the windows badge icon has to be all white. so we have a lot of users run into this issue when we try to map icons in PWABuilder (we are basically stopping to mapping to badges).
Now on the masking, in Windows we do all square icons, but our guidelines actually ask for margin on images: https://docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/app-assets can I assume masking can be interpreted to padding as well, or is that something different?

[kenchris]

@boyofgreen yes, it can, but we need to get the sizes right then. On Android, the safe zone seems to be 1/3 (Matt states 11/36) to each side form the center point, so I don't know how well that fits with Windows.

Looking at the url you gave , it says "For medium tiles, limit the icon width to 66% and height to 50% of tile size"

66% is the same as 1/3 (33%) to both sides from center point, but for height you want 1/4 instead.

[kenchris]

For the above case, the 1/3 would work fine, because 16+16 is 1/3 :-) so in this way "masking" works pretty well for what you define as "fullbleed" images as all the important parts are supposed to be within the inner 2/3rds of the icon

[kenchris]

For list views you have the below:

due to the safe zone of the inner 2/3 if the image, you can without problem cut the other parts so that it fits this

[kenchris]

@boyofgreen we do have a "badge" purpose in the spec at this point, but I am not sure it is being used yet (it was proposed by Googlers, I believe). We might be able to change that to only give a shape, like one color image or so, that seems to fit well with the notification icons Android uses (gray or white shapes, check Twitter, Chrome, etc below)

[boyofgreen]

As you can see there are a lot of different rules that change depending on tile size or the orientation of the icon. Other think to keep in mind is that this is design guidance, and may change as windows UI changes :). the important thing for me is being able to assume at least some of the padding rules, which sounds like I can with masking. I don't feel like it needs to follow every rule, but we want PWAs to avoid the overlapping text / image issues that some tiles may face.

[clagom]

Hello everyone, I’m a co-worker (Interaction/UX designer) of @kenchris
I had looked at the Android adaptive icons while ago, and the official guidelines are very useful and clear. I didn’t know about the “safe zone” area mentioned in the Medium article, but it’s a nice detail to know. I wonder though if it overcomplicates the guidelines if included in the specs with the proportion "11/36". I think providing the image itself as an example would be a simpler explanation, also for designers.
This "safe zone" is not included in the Android guidelines, so could probably be simplified mentioning a ‘1/3’ instead (bigger than the safe area, but still within the margins)?

[kenchris]

Hi @clagom could you create such an image that I can use in the spec? potentially SVG?

[mgiuca]

Hi. The 11/36 from my comment here was based on that Medium article about Android, not any official specs (which I couldn't find).

It's calculated by 33/108, in other words, it's the radius of the safe zone (the inner circle in this picture), as a fraction of the entire image size (including the dead zone for parallax purposes).

This is slightly less than 1/3 (which is why in the above image, the light purple circle is slightly smaller than the dark purple rounded-square). If you just "round it up" to 1/3, then the safe zone is the same radius as the dead zone. Since the dead zone is the space that's guaranteed to be not-seen (when not parallaxing) and the safe zone is the space that's guaranteed to be visible after masking, it doesn't make sense for these to be the same (otherwise you can't mask the edges at all).

Having said that, if we aren't parallaxing, then there is no concept of a dead zone. We can just ignore everything outside of that 72 dp square, and thus the safe zone is simply a 33-dp-radius circle inside a 72-dp icon image. So we can simplify this and say the safe zone is a circle of radius 11/24 (as a fraction of the image side length; i.e., 33/72). That should satisfy Android.

Do we want to tie our boat to Android? Not necessarily, but since we'll be showing it on Android, we should define a safe zone that is equal or smaller than Android's safe zone. So that should be equal to or less than 11/24. I might suggest 2/5 for a fairly round number that's slightly smaller than Android's.

So we would be recommending that the maskable image is a full-bleed image with all critical information (such as text and logo bits) within a circle whose radius is 2/5 the image edge size. For a 72x72 image, that's a circle of radius 28.

[kenchris]

So a radius of 2/5 means that you have 10% non-safe padding on each side, where as the MS guidelines seems to indicate the need for 16% (1/3 in total of both sides).

So example for an android icon of size 192px, the safe zone would take up 4/5 (~= 154px) leaving a non-safe zone margin of 10%.

Windows seems to prefer a margin of around 16% for fullbleed tiles which is slightly more than 10%, but maybe not terrible much. As can be seem on their examples, some of the icon content actually paints outside the inner (2/3 of the image).

So with 2/5 we end up recommending 10% non-safe padding around the safe area, which seems to be slightly less than what Windows recommends today, but still an improvement from what they have today.

Is this fine @boyofgreen ?

[kenchris]

If you look at existing icons on Android today

You will see that even within the safe zone, most of these have some padding, so 10% plus this additional padding that people apply and you get very close to the 16%

[kenchris]

OK, updated PR and added some nice images from @clagom - they don't show up in the preview so posted a few pics on my Twitter: https://twitter.com/kennethrohde/status/968527850361024514

[marcoscaceres]

Make sure this works on mobile, if you haven't already.

[kenchris]

I did test :-) works fine

[marcoscaceres]

Initial feedback.

[marcoscaceres]

Nit: Maybe just talk about "icons" or do we want to define "application icons" specifically.

[marcoscaceres]

s/image/icons

[marcoscaceres]

s/these data/these icons ... or "these images"

[marcoscaceres]

Avoid "may" here. Use "might"

[marcoscaceres]

Nit, just do

<a>badge</a>

And add data-lt="badge purpose" to the dfn of badge.

[marcoscaceres]

Grammar: that is can be placed

[marcoscaceres]

as above with regards to data-lt

[marcoscaceres]

It doesn't feel right to me to define this in the spec. All we should do here is tell developers to seek out guidance from browser vendors.

Does notification API provide any guidance like this?

[kenchris]

Not sure, maybe @beverloo knows

[kenchris]

I am afraid that if we don't add this here, then some vendors will do their own thing and we will end up with a mess

[marcoscaceres]

This should all be moved to MDN instead, IMO.

[kenchris]

Can we remove when things have been merged and that has been added to MDN?

[marcoscaceres]

Sure. That would be fine.

[marcoscaceres]

@mgiuca, did you want to do a round on this?

[kenchris]

From @mgiuca

This has become somewhat urgent since Chrome 69 seems to be upgrading to the Android O SDK and suddenly all the web app icons are going inside white circles (https://crbug.com/862041). It would be good if we can let web apps specify Adaptive icons soon.

Do you think we can start with just the masking (not parallax) so the proposal basically just becomes:

Introduce a new "purpose": "maskable" type of icon.

• Give it semantics of: not supposed to have an alpha channel; define a "safe zone" (such as a circle of some radius around the center) of pixels that must be shown, and say that the user agent may mask off any other pixels outside of the safe zone.
• Optional; a non-maskable icon is still mandatory. And it's completely optional for user agents to use the maskable icons.
• No foreground/background. No "dead zone". Should be fairly straightforward. I think we can commit to implementing this in Chrome.

[kenchris]

@mgiuca you suggested "maskable" - do you prefer that to "masking"?

[mgiuca]

Hmm. Let's consider the purpose word to be used in a sentence like "This is used for ____" or "This is used as a ____". So "badge" means "This is used as a badge." If we picked "mask" it would be misinterpreted as "This is used as a mask." Similarly, I think "masking" reads as "This is used for masking," which I think could be interpreted either way (i.e., this is a mask, or this is an image that has a mask applied to it.)

So I was going to agree with you, but on further thought, I think we do need a word like "maskable" (despite it being ugly). "maskable" unambiguously (I think) means "This can have a mask applied to it."

[kenchris]

@mgiuca could you review this PR? As it is a purpose, it is optional, but that is not stated explicitly, so if you find a place where you think it makes sense to state that, please tell me.

I think it fulfills your requirements, but I probably need to rebase it

Fixed Marcos' comments and we agreed that note with images can be removed later when this is shipping and that has been moved to MDN

[mgiuca]

Gosh, I totally missed this in February! Sorry. Having a look now.

[mgiuca]

Hi Kenneth,

I did a pass over. This is good work. However, I also had a long chat with @dominickng and we're still a bit unsure that this is the direction we want to go in. It's starting to feel too hard to capture these "full bleed" requirements of all the currently known systems (Windows 10, Android 8 and iOS) with a single set of rules.

I'll post some more thoughts on the bug #555. Perhaps we should have a VC to sort this out (I am out until Tuesday).

[mgiuca]

s/these/this ("data" is a mass noun so never plural).

[mgiuca]

size-constrained (hyphenate)

[mgiuca]

"supercomposed" isn't a word. Can you rephrase as "have a user-agent-specified mask applied"?

[mgiuca]

Hmm. Let's consider the purpose word to be used in a sentence like "This is used for ____" or "This is used as a ____". So "badge" means "This is used as a badge." If we picked "mask" it would be misinterpreted as "This is used as a mask." Similarly, I think "masking" reads as "This is used for masking," which I think could be interpreted either way (i.e., this is a mask, or this is an image that has a mask applied to it.)

So I was going to agree with you, but on further thought, I think we do need a word like "maskable" (despite it being ugly). "maskable" unambiguously (I think) means "This can have a mask applied to it."

[mgiuca]

"rectangular" (misspelled)

[mgiuca]

I think you got these from @clagom on the other thread. Do we have rights to use these or transfer them to W3C copyright.

[kenchris]

The original icon (for my demo project), and I believe the additional graphics, were done as part of Intel work, so we are fine with re-licensing that to W3C copyright.

[clagom]

Yes I worked on those examples when I was at Intel, no problem

[mgiuca]

I'm not sure where this "margins" one came from. Is this 1/5 corners a normative requirement anywhere, or just a recommendation for space to avoid putting important things in? Shouldn't we simply recommend avoiding putting important things anywhere outside of the safe zone?

I think delete this.

[mgiuca]

Needs a "see [Icons]".

[mgiuca]

Drop the link (which links to this very sentence) or link up to the masking section above.

[mgiuca]

I think we should either:

• a) Require that the icons have no alpha channel or transparent pixels (not as a MUST requirement, but specify that it's invalid if it does), or
• b) Specify what happens if they do have transparent pixels. For example, we could say it MUST get pasted onto a white background, or a solid colour of user agent choice.

The idea is that these should be full-bleed images.

[mgiuca]

Ken, just touching base on this.

Looks like the last activity on this was Dom's review. Are you OK with moving forward?

Do you need anything from us (like a commitment from our Android team to implement?). I'll try to get some eyeballs on it.

[kenchris]

Oh sorry, i missed this, let me update the PR

[kenchris]

@mgiuca So fixed Dominick's comments. I think a commitment to implement and then a positive review from you and then we can merge

[mgiuca]

Cool, I'll take a look. Do you want a commitment from just us (Google) or multiple vendors?

[dominickng]

LGTM % minor nit

[dominickng]

Nit: indent by 2 spaces for consistency

[kenchris]

Nit fixed! (tabs vs spaces issue as I had to use VIM as Linux graphics apps broke in last Chrome OS dev update)

@mgiuca want to merge? or do you still need some confirmation?

[anssiko]

If you want to link to the "Icon masks and safe zone" section and not to the maskable definition, it'd be better to expand <a href="#icon-masks">icon masks and safe zone</a>.

(<a>markable</a> should work if you link to its definition.)

[anssiko]

I'd prefer to use non-normative language in this para i.e. s/may/can/g and list normative statement in the list below.

[mgiuca]

A few comments on the wording, but generally this change (normatively) looks good.

[mgiuca]

"supercompose" is not a word. And drop the comma.

It doesn't make sense for the icon to "make sure" of something; the designer needs to make sure.

"must" is a special RFC 2119 word which we shouldn't use here, because this isn't a strict requirement. We could use "SHOULD", but I'm not sure if web specs are supposed to use RFC 2119 language on things we require from developers. (In my mind, we should only impose requirements on user agents, and state how they deal with all sorts of input.)

That makes this a non-normative note. Which means you can't define "safe zone" inside it. So a suggested rewrite:

The <dfn>safe zone</dfn> is the area within a <a>maskable</a> icon which is
guaranteed to always be visible, regardless of user agent preferences. It is defined
as a circle with center point in the center of the icon and with a radius of 2/5 (40%)
of the icon size, which means the smaller of the icon width and height, in case the
icon is not rectangular.

<p class="note">
Designers of <a>maskable</a> icons will want to make sure that all important parts
are within the <a>safe zone</a>.
</p>

[kenchris]

done, used your text

[mgiuca]

Missing word "to" (as in: "are not guaranteed to (but can) be visible").

[kenchris]

added

[mgiuca]

s/applies/applied.

[kenchris]

done

[mgiuca]

s/paste/composite.

Also it's a bit unclear what "any image" means (it refers to the icon, not just any random image).

So: "If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid ..."

Also, suggest adding a non-normative note: "It is suggested that designers avoid using transparent pixels in maskable icons." (Again, avoiding RFC 2119 word "recommended".)

[kenchris]

done

[mgiuca]

s/recommended/suggested

[kenchris]

done

[mgiuca]

Hi Ken, I wonder if you have time to look at the above rewording changes?

[kenchris]

Sure, for some reason, I totally forgot about this

[mgiuca]

nit: The word "solid" was dropped ("solid color"). Maybe you thought it was unnecessary. I don't mind either way.

[mgiuca]

lgtm (with a small nit).

Thanks for persisting on this, Ken.

[ghost]

As per the current spec, on Android the browser will have to crop/apply-mask before sending the icon to platform (like showing on homescreen, recents and settings). It will also have to apply shadows for background protection. This is because the spec only accounts for the safe-zone and not the extra padding for parallex.

But for adaptive icon, platform expects an unmasked/original image so that it can apply consistent badging and shadow treatment.

[dominickng]

@sunnygoyal2 that's kind of the point here though. We explicitly wanted to not have an Android-specific feature, but a web-platform feature. User agents implementing on Android will apply the appropriate transform to fit Android's API requirements.

We also explicitly did not spec the foreground/background image that Android wants, specifically because no other platform has anything like the parallax feature. Instead we will just provide Android with a background image, which is sufficient for masking purposes.

[ghost]

Android does have an API which takes a single bitmap and converts it into an Android Icon representation:
https://developer.android.com/reference/android/graphics/drawable/Icon.html#createWithAdaptiveBitmap(android.graphics.Bitmap).
which allows apps (User agents in this case) to not worry about the actual conversion logic.

Also browser would not be able to provide a proper conversion as the shadow changes based on the surface the icon is displayed on. And since the platform will get the final masked icon, it can't tell if the user-agent masked it the right way.

Even when proving just the background, could it comply with the android icon guidelines? That would allow it to enjoy all the android specific features, and appear consistent with other icons.

[mgiuca]

Android does have an API which takes a single bitmap and converts it into an Android Icon representation:
https://developer.android.com/reference/android/graphics/drawable/Icon.html#createWithAdaptiveBitmap(android.graphics.Bitmap).
which allows apps (User agents in this case) to not worry about the actual conversion logic.

This doesn't make sense to me. The only description of this method is "Create an Icon pointing to a bitmap in memory that follows the icon design guideline defined by AdaptiveIconDrawable.", but it takes a single Bitmap and AdaptiveIconDrawable guidelines are all about how a foreground layers on a background.

I just don't really see what this method is supposed to do (or how it is relevant here).

Also browser would not be able to provide a proper conversion as the shadow changes based on the surface the icon is displayed on. And since the platform will get the final masked icon, it can't tell if the user-agent masked it the right way.

Right. The "safe zone" as defined in the spec is insufficient to simply use the supplied image as a background on Android, because Android defines a much larger "dead zone" around the "safe zone". So the user agent needs to extend the image to satisfy the cropping requirements of the host platform.

This isn't (really) anything to do with parallax or dead zone vs safe zone. You can simply think of it as Android's "safe zone" is much smaller than the "safe zone" we defined in this spec (the web spec safe zone is 80% diameter, while Android's safe zone is 61% diameter). That's fine, it just means the image needs to be padded to display correctly on Android. It didn't make sense to have the web spec exactly match Android (the web is bigger than just Android).

This is all explained in my July 11 post on the bug, with calculations and sample images. (Option B is what we ended up going with.)

Even when proving just the background, could it comply with the android icon guidelines? That would allow it to enjoy all the android specific features, and appear consistent with other icons.

We don't want to have the web spec demand that developers supply an image compatible with Android icon guidelines. That unnecessarily biases the spec towards Android. We spec the "lowest common denominator" which can be used across many platforms. For example, iOS user agents can adjust the image as required there.

[ghost]

This isn't (really) anything to do with parallax or dead zone vs safe zone. You can simply think of it as Android's "safe zone" is much smaller than the "safe zone" we defined in this spec (the web spec safe zone is 80% diameter, while Android's safe zone is 61% diameter). That's fine, it just means the image needs to be padded to display correctly on Android. It didn't make sense to have the web spec exactly match Android (the web is bigger than just Android).

Oops. I think I was assuming all the pixels on the provided icon to be non-transparent, in which case it would be difficult for user-agents to add additional padding.
That doesn't look like the case from the sample at https://w3c.github.io/manifest/#icon-masks

[mgiuca]

You're correct that all the pixels are supposed to be opaque in a maskable icon:

If the icon contains transparent pixels, the user agent MUST composite the icon onto a solid color (eg. white) of the user agent's choice.

NOTE: It is suggested that designers avoid using transparent pixels in maskable icons.

The idea is that you supply a "full-bleed" square icon with no transparent pixels.

When you say "it would be difficult for user-agents to add additional padding"... I guess you mean if the icon was a non-square icon with transparent pixels, you can just extend the transparency outwards. But with a "full-bleed" square icon, how do you do that? This is true, but we figured the user agent could just extend it out with black pixels, which will never be seen because Android masks out the background and doesn't parallax it (it only parallaxes the foreground). To be very sure, the user agent could extend the pixels at the edge of the image outwards, instead of just using black.

Again, see my July 11 post, where one of the images has a thick black border around it; that simulates the Android user agent's extending the image to match Android's required dimensions.