Re: [w3c/manifest] Add a 'masking' purpose, for allowing the UA to supercompose such icons (#657)

mgiuca commented on this pull request.

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

> @@ -2570,6 +2604,143 @@ <h3>
           </pre>
         </div>
       </section>
+      <section>
+        <h2><a id="icon-masks"></a>
+          Icon masks and safe zone
+        </h2>
+        <p>
+          Some platforms have their own preferred icon shape, but as web
+          applications should work across multiple platforms, it is possible to
+          indicate that an icon can have a user-agent-specified mask applied by
+          adding the <a>maskable</a> purpose. This allows the platform to ensure
+          that the icon looks well integrated with the platform, and even apply
+          different masks and background colors in different places throughout
+          the platform.
+        </p>
+        <p>
+          Any icon indicating that it can be supercomposed with a mask, must

"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:

```html
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>
```

> +          zone</dfn>, which 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>
+        <figure>
+          <img src="images/safe-zone.svg" width="340" height="340" alt=
+          "safe zone illustrated">
+          <figcaption>
+            The safe zone is a centrally positioned circle, with radius 2/5
+            (40%) of the minimum of the icon's width and height.
+          </figcaption>
+        </figure>
+        <p>
+          All pixels in this zone are guaranteed to be seen in all masks.
+          Pixels outside the safe zone are not guaranteed (but can) be visible

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

> +          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>
+        <figure>
+          <img src="images/safe-zone.svg" width="340" height="340" alt=
+          "safe zone illustrated">
+          <figcaption>
+            The safe zone is a centrally positioned circle, with radius 2/5
+            (40%) of the minimum of the icon's width and height.
+          </figcaption>
+        </figure>
+        <p>
+          All pixels in this zone are guaranteed to be seen in all masks.
+          Pixels outside the safe zone are not guaranteed (but can) be visible
+          depending on the applies mask.

s/applies/applied.

> +        </p>
+        <p>
+          The user agent MAY apply a mask of any size, making any pixels that
+          are more than 2/5ths of the image size (minimum of width and height
+          if non-square) away from the center (the <a>safe zone</a>)
+          transparent.
+        </p>
+        <p>
+          The user agent MUST NOT make any pixel within the safe zone
+          transparent.
+        </p>
+        <p>
+          The user agent MAY enlarge the icon by adding additional padding.
+        </p>
+        <p>
+          The user agent MUST paste any image containing transparent pixels

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".)

> +        <p>
+          The user agent MAY enlarge the icon by adding additional padding.
+        </p>
+        <p>
+          The user agent MUST paste any image containing transparent pixels
+          onto a solid color (eg. white) of the user agent's choice.
+        </p>
+        <section>
+          <h3>
+            Examples of masks
+          </h3>
+          <p class="note">
+            By staying inside the <a>safe zone</a>, most icons will have around
+            10% padding on the top, bottom, right and left with no content or
+            non-essential content, such as an icon background.
+            It is recommended that developers check their icon when all but the

s/recommended/suggested

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/pull/657#pullrequestreview-152323614