Skip to content
Open
Changes from 6 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
ea96466
Replace asking for users for consent with designing for user intent
mharbach Sep 11, 2025
c028359
Updates in response to comments from @hober and @martinthompson
mharbach Sep 12, 2025
efbf7bc
Addressed further comments from @martinthomson
mharbach Sep 23, 2025
c8d0fc8
Merge branch 'main' into patch-1
mharbach Sep 23, 2025
609b59a
Fixed more inconsistent apostrophes
mharbach Sep 23, 2025
9c642d9
Merge branch 'patch-1' of https://github.com/mharbach/design-principl…
mharbach Sep 23, 2025
67596e2
Apply suggestion from @martinthomson
mharbach Sep 25, 2025
723632e
Apply suggestion from @martinthomson
mharbach Sep 25, 2025
e8a9a6c
Apply suggestion from @martinthomson
mharbach Sep 25, 2025
462df7e
Addressed remaining comments from @martinthomson
mharbach Oct 2, 2025
aede8a0
Merge branch 'main' into patch-1
mharbach Oct 7, 2025
3148189
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
87bc056
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
7754dca
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
6f8fd9c
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
c7b38c1
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
12c179a
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
960856d
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
63307ee
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
63450e9
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
52b7f0d
Apply suggestion from @jyasskin
mharbach Oct 7, 2025
d500053
removed a superfluous comma.
mharbach Oct 7, 2025
bf0f95a
Included suggestions from @jyasskin
mharbach Oct 8, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 79 additions & 55 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -161,57 +161,81 @@ This is often used to attempt to trick users into visiting scam websites.
If this feature was proposed today, it would probably not proceed.
</p>

<h3 id="consent">Ask users for meaningful consent</h3>
<h3 id="user-intent">Design for user intent</h3>

In the context of fulfilling a user need,
a web page may want to make use of a feature
that has the potential to cause harm.
Features that have this potential for harm should be designed such that people can give
[meaningful consent](https://www.w3.org/2001/tag/doc/ethical-web-principles/#control) for that feature to be used,
and that they can refuse consent effectively.

In order to give *meaningful consent*, the user must:
- **understand** what permission they may choose whether to grant the web page
- be able to choose to give or refuse that permission **effectively**.

If a feature is powerful enough to require user consent,
but it's impossible to explain to a typical user what they are consenting to,
that's a signal that you may need to reconsider the design of the feature.

If a permission prompt is shown,
and the user doesn't grant permission,
the Web page should not be able to do anything
that the user believes they have refused consent for.

By asking for consent,
we can inform the user of what capabilities the web page does or doesn't have,
reinforcing their confidence that <a href="#safe-to-browse">the web is safe</a>.
However, the <a href="#priority-of-constituencies">user benefit</a>
of a new feature must justify the additional burden on users
to decide whether to grant permission for each feature
whenever it's requested by a Web page.
Using such a feature should only be possible
if the user's expectation matches the feature's consequences
(e.g., personal information used, state changed).

Design your API so its behavior matches what people intend and expect.
Then, in the best case, people don't need to get involved in allowing API access
and thus can't make decisions they regret later.
Only ask the user for confirmation in exceptional circumstances.
If a capability can be easily reverted or causes only mild annoyance without the chance for permanent harm,
afford users an option to stop capability access instead.

<p class="example">
For example, web pages don't need to ask for permission to play sounds.
It is easy to stop audio output if a site is found to be abusing it
and browsers have a number of mechanisms for doing just that.
Similarly, PWAs wanting to use [Window Control Overlay](https://wicg.github.io/window-controls-overlay/) don't need to ask for permission,
as the user simply toggles this mode on when they need it.
</p>

<h4 id="user-decisions">Help users make good decisions</h4>

Empower good decision-making by limiting risk at the API level and
providing clarity, context, and user control.
Asking for user approval has been a common way to handle remaining risk.
However, most people can't make good decisions on
many of the questions they're asked
because they lack crucial context and information.
Being confronted with difficult or annoying questions leads
to decision fatigue, habitual responses,
annoyance from frequent interruptions, and regrettable decisions.

When user involvement is unavoidable,
empower users to make good decisions.
Use these principles:

* **Limit the consequences from a bad decision by addressing risk at the API level first.**
Do not ask users questions where a "bad" decision can lead to severe consequences,
like a compromised device or serious personal data disclosure.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a little concerned about this absolute statement, when the ubiquitous "download this file" and "fill in this form" features violate it. But principles can always be violated with a good reason, so I don't object to keeping it.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point and I think these features do violate the principle for good reasons. These seem to be table-stakes-type features that enable a large number of use cases. Maybe if they didn't exist today, we might be hesitant to ship them, given what we know about abuse on the web. But yes, I still believe this is a good principle to keep.

* **Provide constant feedback about persistent decisions.**
If users' decisions last longer than the current session,
user agents should remind users that their past decision still applies.
Provide a way to retract any ongoing permission,
including APIs to inform sites of the change in status.
* **Ask questions people can understand.**
The associated risks should be obvious from the question for a typical user
and be directly connected to the feature's or API's utility.
For example, this usually means we can't ask permission to accept fingerprinting risks,
as they are subtle, technical, and commonly have nothing to do with the capability itself.
* **Provide sufficient context.**
People need to easily understand who they're dealing with,
what the decision is about, and how the website will use any information they might share.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"how the website will use any information they might share" isn't usually something the UA can ensure the user is told, especially with our historical resistance to include website-provided strings in browser UI.

I'm ok with keeping the text anyway because I don't have any suggestions for how to fix it.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it is something that we haven't ever solved for on the web platform, but other platforms have and I hope that we can start doing more of it in the future. So this is indeed more aspirational.

* **Let people make decisions when *they* are ready.**
Websites should not be able to force the decision moment on the user,
while they're trying to do something else.
Instead, people should be able to choose the decision moment,
for example by clicking on a dedicated button like for the file chooser.

If you can't adhere to all of the above principles,
that is likely an indication that asking the user isn't the right approach.
Instead, change the feature or API to address any remaining risk.

In your specification, the [=request permission to use=] and [=prompt the user to choose=] algorithms from [[permissions]] are good ways to ask for consent.

If you ask a user to make a decision and they say no, the website shouldn't be able to do anything the user believes they just refused access to.

Refusal is most effective if the site cannot
distinguish refusal from other, common situations.
This can make it more difficult for a site to
pressure users to grant consent.

<p class="example">
For example,
the [Geolocation API](https://www.w3.org/TR/geolocation-API/)
grants access to a user's location.
This can help users in some contexts,
like a mapping application,
but may be dangerous to some users in other contexts -
especially if used without the user's knowledge.
So that the user may decide whether their location may be used by a Web page,
a permission prompt should be shown to the user asking whether to grant location access.
If the user refuses permission,
no location information is available to the Web page.
</p>

See also:

* [The web is secure, and respects people's privacy](https://www.w3.org/2001/tag/doc/ethical-web-principles/#privacy)
Expand Down Expand Up @@ -243,7 +267,7 @@ actively collected (for example, they have filled in a form).
For such features, you should [understand the context](https://www.w3.org/TR/privacy-principles/#identity)
in which it will be used,
including how it will be used alongside other features of the web.
Make sure the user can [give appropriate consent](#consent).
Make sure to [design for user intent](#user-intent) and [help users make good decisions](#user-decisions).
Design APIs to collect
[the smallest amount of data](https://www.w3.org/TR/privacy-principles/#data-minimization)
necessary.
Expand Down Expand Up @@ -367,7 +391,7 @@ APIs should also provide granularity and user controls,
in particular over <a href="https://www.w3.org/TR/privacy-principles/#dfn-data">personal data</a>,
that is communicated to sites.
When additional functionality requires additional data, APIs can enable this
subject to user consent (e.g., a permission prompt or user activation).
if they [design for user intent](#user-intent) and [help users make good decisions](#user-decisions) when necessary.

<div class=example>
A <a href="#font-enumeration">Font Enumeration API</a> API was once proposed, but the tradeoff of user data exposed was not justified by the use cases. Instead, an alternative solution was proposed, which only exposed the font the user actually selected.
Expand Down Expand Up @@ -585,8 +609,7 @@ if feature detection were available for the feature,
then you should not support feature detection.

Detecting the availability of a feature does not imply
detecting whether <a href="#consent">consent</a> to use the feature
has been granted.
detecting whether [the user has been asked](#user-decisions) to use the feature.
Generally, detecting whether the feature is implemented
can be done separately from determining whether use of the feature has been authorized.
In some cases, it might be necessary to disable feature detection
Expand All @@ -605,7 +628,7 @@ See also:
* [[#do-not-expose-use-of-private-browsing-mode]]
* [[#do-not-expose-use-of-assistive-tech]]
* [[#secure-context]]
* [[#consent]]
* [[#user-decisions]]

<h3 id=text-formats>Design textual formats for humans</h3>

Expand Down Expand Up @@ -769,8 +792,7 @@ a single user’s activity
both in and out of private browsing mode,
consider possible [mitigations](https://www.w3.org/TR/security-privacy-questionnaire/#mitigations)
such as introducing noise,
or using permission prompts to give the user extra information
to help them meaningfully consent to this tracking (see [[#consent]]).
or [helping users make good decisions](#user-decisions) about this tracking, if necessary.

Private browsing modes enable users to browse the web
without leaving any trace of their private browsing on their device.
Expand Down Expand Up @@ -814,7 +836,8 @@ that site can deny or restrict the user's access to the services it provides.
People who make use of assistive technologies
are often [vulnerable members of society](https://www.w3.org/2001/tag/doc/ethical-web-principles/#noharm);
their use of assistive technologies is [sensitive information](https://www.w3.org/TR/security-privacy-questionnaire/#sensitive-data) about them.
If an API provides access to this information,
If an API provides access to this information
without [asking the user](#user-decisions),
this sensitive information may be revealed to others
(including [state actors](https://www.w3.org/2001/tag/doc/ethical-web-principles/#expression))
who may wish them harm.
Expand Down Expand Up @@ -865,8 +888,8 @@ once per API call ([transient consuming](https://html.spec.whatwg.org/#activatio

Note that while user activation is in many cases necessary,
it is not always *sufficient*
to protect users from invasive behaviours,
and seeking [meaningful consent](#consent) is also important.
to protect users from invasive behaviours.
[Designing for user intent](#user-intent) and [helping users to make good decisions](#user-decisions) is also important.

<h3 id="support-non-fully-active">Support non-fully active BFCached documents</h3>

Expand Down Expand Up @@ -2118,7 +2141,7 @@ Promise-using code also tends to be easier to understand
than code using callback functions.

An API might need to be asynchronous if:
* the user agent needs to prompt the user for [permission](#consent),
* the user agent needs to prompt the user for [permission](#user-decisions),
* some information might need to be read from disk,
or requested from the network,
* the user agent may need to do a significant amount of work on another thread,
Expand Down Expand Up @@ -2986,9 +3009,8 @@ use these guidelines when exposing device information:
: Hide sensitive information behind a user permission
:: If you can't create a device identifier in an anonymous way,
limit access to it.
Make sure the user can provide
[[#consent|meaningful consent]]
to a Web page accessing this information.
Make sure you [help the user make good decisions](#user-decisions)
about a Web page accessing this information.
: Tie identifiers to the same-origin model
:: Create distinct identifiers for the same physical device
for each origin that has has access to it.
Expand All @@ -3009,7 +3031,7 @@ use these guidelines when exposing device information:

See also:

* [[#consent]]
* [[#user-decisions]]
* [[LEAST-POWER]]
* [[FINGERPRINTING-GUIDANCE]]
* [[UNSANCTIONED-TRACKING]]
Expand All @@ -3033,7 +3055,7 @@ you may not need to expose a list to script at all.
An API which invokes a User-Agent-provided device picker could suffice.
Such an API:
- keeps the user in control,
- doesn't expose any device information without the user's [consent](#consent),
- [helps users understand](#user-decisions) their decisions,
- doesn't expose any fingerprinting data about the user's environment by default, and
- only exposes information about one device at a time.

Expand All @@ -3043,6 +3065,8 @@ the fact that there are devices are available to be picked.
This does expose one bit of fingerprinting data about the user's environment
to websites,
so it isn't quite as safe as an API which doesn't have such a feature.
Ensure that such an API ensures that it is possible to present sufficient information
on user interfaces that users are able to [make good decisions](#user-decisions).

<div class=example>
The {{RemotePlayback}} interface
Expand Down