Update explainer to include details about the icon

HOWTO.md

@@ -124,6 +124,20 @@ rules as their equivalent.
 
 You can use the `:granted` CSS pseudo-class to target permission elements for which the permission is already granted in order to use a different style for them.
 
+The icon can be selected and styled using the `::permission-icon` selector. The styling of the icon is also restricted and controlled. Only the following CSS properties can be used on the icon.
+
+| Property            | Rules |
+| ---                 | ---   |
+| `display`           | Can be used to show or hide the icon. It is visible by default and can be hidden using `display: none`.
+| `fill`              | Can be used to change the color of the icon. |
+| `stroke`            | Can be used to change the color of the outline of the icon |
+| `stroke-width`      | Can be used to change the thickness of the outline of the icon |
+| `height`            | Will have a default value of 1.3em. It can be set to anything between 0 and 1.5em. Note that the width will always be equal to the height. |
+| `min-height`        | Values over 1.5em will be corrected to to 1.5em |
+| `max-height`        | Can be used as normal, but the height will never exceed 1.5em |
+| `margin-inline-end` | Can be used to control the distance between icon and text, limited to 3em. Other margins are immutable. |
+
+
 ## Providing feedback
 If you're a dev and you have feedback for improvements on the ergonomics or shape of the API, please feel free raise an issue against this repository.
 

explainer.md

@@ -77,7 +77,7 @@ Therefore, a more confident signal of user intent is key to making web permissio
 
 The semantic `<permission>` HTML element will serve as an in-content entry point for permission requests, appearing and functioning much like any other HTML button [Image A]. The crucial difference is that a click on this button will trigger a permission request for which the user agent can have high confidence that it was user-initiated [Image C]. To achieve a strong signal of user intent, user agents require [user activation](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation) to let a script trigger a permission prompt.
 
-The `<permission>` element comes with browser-controlled content and styling constraints to prevent manipulation and ensure its integrity. This design unifies permission control by offering a clear, consistent, in-page access point for managing permissions in both the browser and the OS.
+The `<permission>` element comes with browser-controlled content(text and icon) and styling constraints to prevent manipulation and ensure its integrity. This design unifies permission control by offering a clear, consistent, in-page access point for managing permissions in both the browser and the OS.
 
 User agents can combine the element with a louder, more opinionated design to emphasize the critical decision moment. Other user agents can tailor this experience to their needs while relying on the strong user signal the element provides. For instance, Chrome is doing an implementation that combines this semantic HTML element [Image A] with a full-page modal confirmation UI [Image B,C] that applies a scrim to obscure underlying site content during the critical decision moment. Regardless of the specifics, the `<permission>` element makes manipulation and "change blindness" more difficult. Browsers maintain strict control over the content presented to the user, ensuring it aligns with their understanding of user intent. This approach significantly enhances user intent capture, improving accessibility, security, and user-friendliness for both users and developers. The element also includes appropriate safeguards to protect users from common spam and abuse patterns such as clickjacking.
 
@@ -92,7 +92,7 @@ User agents can combine the element with a louder, more opinionated design to em
     </td>
   </tr>
 </table>
-<p> <em>Image 3: Implementation example: A video conferencing site providing a "Use microfone" button and a search site a "Use precise location" button, that triggers a microfone or geolocation permission request. </em> </p>
+<p> <em>Image 3: Implementation example: A video conferencing site providing a "Use microphone" button and a search site a "Use precise location" button, that triggers a microphone or geolocation permission request. </em> </p>
 
 
 
@@ -342,7 +342,7 @@ After a user clicks the `<permission>` element, a browser-controlled confirmatio
 - **UI When Request is Otherwise Blocked:** User agents implement many mechanisms to prevent permission requests, such as permanent denies (explicit or implicit), duration-based denies, heuristics, blocklists, or ML-based automatic blocks. Each of these mechanisms should be carefully weighed against the strong signal sent by the user clicking the `<permission>` element. This strong signal might override some of these mechanisms entirely (e.g., heuristics or ML models might not apply to `<permission>` element-triggered prompts) or lead to a compromise. For example, if a site is in a "deny" state but the user clicks the `<permission>` element, the confirmation UI could appear as: "You previously didn't allow camera on example.com" with options like "Continue not allowing" and "Allow once”. In such a case, offering "Allow once" instead of a permanent "Allow" is a deliberate choice to be on the safe side, given the user previously denied the permission. If the user then clicks the `<permission>` element again on the next visit, they would see the standard browser prompt for a full "Allow" decision.
 <img src="images/secondary - previously denied.png" width="300" alt="Description of image18">
 
-- **Flexibility and Future UI Considerations:** The `<permission>` element proposal does not prescribe any particular prompt UI or exact text to browsers. This flexibility allows user agents to optimize their native prompt display for specific platforms and user expectations, including handling internationalization and cultural differences, a task browsers already manage for existing prompts. Despite these UI and linguistic variations, the `<permission>` element ensures consistent, browser-controlled content and semantic meaning during the critical decision moment. <br/> Future considerations for the `<permission>` element's visual design include evolving from text-only (status quo) to 'Icon + Text' and potentially 'Icon only' displays.  To facilitate seamless visual integration with diverse website designs and ensure universal user understanding, we have conducted an audit of the most common and universally understood strings and icons used across the web, which will be incorporated as options for the `<permission>` element. We are actively evaluating additional string and icon options as the element gains wider adoption, and we remain open to community feedback for its continued relevance and usability.  It's noted that in-call controls are not a primary use case for the `<permission>` element in the near future. For certain low-risk capabilities (e.g., sharing a single set of coordinates or clipboard read), a future design evolution could allow skipping the secondary confirmation UI entirely, while high-risk capabilities like camera and microphone would retain it. 
+- **Flexibility and Future UI Considerations:** The `<permission>` element proposal does not prescribe any particular prompt UI or exact text to browsers. This flexibility allows user agents to optimize their native prompt display for specific platforms and user expectations, including handling internationalization and cultural differences, a task browsers already manage for existing prompts. Despite these UI and linguistic variations, the `<permission>` element ensures consistent, browser-controlled content and semantic meaning during the critical decision moment. <br/> Future considerations for the `<permission>` element's visual design include evolving from 'Icon + Text' (status quo) to potentially 'Icon only' displays.  To facilitate seamless visual integration with diverse website designs and ensure universal user understanding, we have conducted an audit of the most common and universally understood strings and icons used across the web, which will be incorporated as options for the `<permission>` element. We are actively evaluating additional string and icon options as the element gains wider adoption, and we remain open to community feedback for its continued relevance and usability.  It's noted that in-call controls are not a primary use case for the `<permission>` element in the near future. For certain low-risk capabilities (e.g., sharing a single set of coordinates or clipboard read), a future design evolution could allow skipping the secondary confirmation UI entirely, while high-risk capabilities like camera and microphone would retain it. 
 Strict styling restrictions, detailed in "Security and Abuse Mitigation," are paramount. These browser controls prevent manipulative or misleading framing, ensuring element integrity and user protection from deceptive practices.
 <br/> While embedding the `<permission>` element increases design challenges (e.g., layout issues from browser variations), the proposal prioritizes consistent semantic meaning and user intent capture over uniform UI. We believe its significant benefits for users (reduced annoyance, better control, easier recovery) and developers (clearer intent, fewer troubleshooting burdens) will encourage design adjustment for optimal integration.