From 5f457b973d5b9ad5d88667bf57472446530e7eba Mon Sep 17 00:00:00 2001
From: Daniel Vogelheim <vogelheim@chromium.org>
Date: Mon, 10 Feb 2025 17:04:41 +0100
Subject: [PATCH 1/2] Add presentation section.

---
 permission-element.bs | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/permission-element.bs b/permission-element.bs
index 88c9d54..293a4f7 100644
--- a/permission-element.bs
+++ b/permission-element.bs
@@ -583,8 +583,6 @@ To <dfn for="HTMLPermissionElement">recheck type permissibility</dfn> for a
 
 # Rendering the <{permission}> Element # {#rendering}
 
-## Presentation ## {#presentation}
-
 The <{permission}> element is a [=non-devolvable widget=] and is chiefly
 rendered like a <{button}>. The button label is largely expected to be
 determined by the browser, rather than the page, and reflects the
@@ -595,6 +593,31 @@ constraints to prevent abuse (e.g. minimum and maximum sizes for fonts and
 the label itself). The page can also select a locale for the text via the
 <{html-global/lang}> attribute.
 
+## Presentation ## {#presentation}
+
+The [=user agent=] is largely free to render the <{permission}> element
+in a way it thinks best conveys the element's intent. Expectations for
+the <{permission}> element's presentation include:
+
+* Name the [=powerful features=] listed in {{[[Types]]}}, in the language
+    indicated by the [=language=] of the element. Note that this would
+    always be the language indicated by the <{html-global/lang}> attribute,
+    if present.
+* An icon indicating the [=powerful feature=] type.
+* The current [=permission state=] of the [=powerful feature=] in questions.
+    For example, if {{[[Types]]}} is `"camera"` then an indication of whether
+    camera access is currently {{PermissionState/granted}} or
+    {{PermissionState/denied}} might improve user experience.
+
+[=User agents=] are encouraged to name or describe the [=powerful features=]
+in a way that's consistent with similar usage in program or the platform it
+is running on.
+
+Very non-normative examples might be:
+
+* `<permission lang="de" types="geolocation">`: "Standort verwenden".
+* `<permission types="microphone">` (in an English language page): "Use microphone. &#x1f3a4;".
+
 ## Styling ## {#style}
 
 A <{permission}> element constrains the styling that can be applied to it.

From aac75c2170e2fe3a4c9cec69fc7fc799d201df3c Mon Sep 17 00:00:00 2001
From: Daniel Vogelheim <vogelheim@chromium.org>
Date: Tue, 11 Feb 2025 18:50:34 +0100
Subject: [PATCH 2/2] edits

---
 permission-element.bs | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/permission-element.bs b/permission-element.bs
index 293a4f7..a820fa4 100644
--- a/permission-element.bs
+++ b/permission-element.bs
@@ -595,19 +595,32 @@ the label itself). The page can also select a locale for the text via the
 
 ## Presentation ## {#presentation}
 
-The [=user agent=] is largely free to render the <{permission}> element
-in a way it thinks best conveys the element's intent. Expectations for
-the <{permission}> element's presentation include:
+ISSUE: There isn't much precedence for describing the user agent UI in detail.
+    It may be better to leave more freedom to user agents.
+
+The <{permission}> element contains browser-chosen content, text and maybe an
+icon. Activating it will [=prompt the user to choose=].
+This provides two bits of user interface that a user can interact with.
+The [=user agent=] is largely free to determine these &mdash; rendering of the
+<{permission}> element and the subsequent [=prompt the user to choose|permission
+prompt=] &mdash; in whichever way it thinks best convey's the element's intent.
+
+
+UI options for the <{permission}> element's presentation include:
 
 * Name the [=powerful features=] listed in {{[[Types]]}}, in the language
     indicated by the [=language=] of the element. Note that this would
     always be the language indicated by the <{html-global/lang}> attribute,
     if present.
-* An icon indicating the [=powerful feature=] type.
+* An icon indicating the [=powerful feature=] type or types.
 * The current [=permission state=] of the [=powerful feature=] in questions.
-    For example, if {{[[Types]]}} is `"camera"` then an indication of whether
-    camera access is currently {{PermissionState/granted}} or
-    {{PermissionState/denied}} might improve user experience.
+    For example, if the [=powerful feature|permission=] is already
+    {{PermissionState/granted}}, the <{permission}> element might be labeled
+    as "geolocation already in use".
+* A modal [=prompt the user to choose|prompt=] with a "scrim".
+    (I.e., darkening out the page behind the prompt.)
+    This would normally quite disruptive. But here our goal is to ensure a
+    user means to make this choice.
 
 [=User agents=] are encouraged to name or describe the [=powerful features=]
 in a way that's consistent with similar usage in program or the platform it
@@ -617,6 +630,9 @@ Very non-normative examples might be:
 
 * `<permission lang="de" types="geolocation">`: "Standort verwenden".
 * `<permission types="microphone">` (in an English language page): "Use microphone. &#x1f3a4;".
+* Upon activiating `<permission types="microphone">`, when the corresponding
+    [=permission state=] is {{PermissionState/denied}}, modify the text to
+    "Continue blocking".
 
 ## Styling ## {#style}