<pre class="metadata">

Title: Web Platform Design Principles

Group: tag

Shortname: design-principles

Repository: w3ctag/design-principles

Status: NOTE-ED

Level: none

TR: https://www.w3.org/TR/design-principles/

ED: https://w3ctag.github.io/design-principles/

Issue Tracking: GitHub https://github.com/w3ctag/design-principles/issues/

Editor: Jeffrey Yasskin, w3cid 72192, Google https://www.google.com/

Former Editor: Martin Thomson, w3cid 68503, Mozilla https://www.mozilla.org/, https://lowentropy.net/

Former Editor: Lea Verou, Invited Expert, https://lea.verou.me, w3cid 52258

Former Editor: Sangwhan Moon, w3cid 42399, Google https://www.google.com/, https://sangwhan.com

Former Editor: Domenic Denicola, Google https://www.google.com/, https://domenic.me/, d@domenic.me

Former Editor: Travis Leithead, Microsoft, travil@microsoft.com

Abstract: This document contains a set of design principles to be used when designing web platform technologies. These principles have been collected during the Technical Architecture Group's discussions in <a href="https://github.com/w3ctag/design-reviews/">reviewing</a> developing specifications, and build upon the Ethical Web Principles [[ethical-web-principles]]. We encourage specification designers to read this document and use it as a resource when making design decisions.

Default Biblio Status: current

Markup Shorthands: markdown on

Boilerplate: feedback-header off

!By: <a href="https://www.w3.org/2001/tag/">Members of the TAG</a>, past and present

!Participate: <a href="https://github.com/w3ctag/design-principles">GitHub w3ctag/design-principles</a> (<a href="https://github.com/w3ctag/design-principles/issues/new">file an issue</a>; <a href="https://github.com/w3ctag/design-principles/issues?state=open">open issues</a>)

Required IDs: using-http

Link Defaults: html (dfn) queue a task/in parallel/reflect

</pre>

<pre class="link-defaults">

spec:css-cascade-5; type:dfn; text:inherit

spec:html; type:event; for:Window; text:load

spec:html; type:event; text:resize

spec:payment-request; type:attribute; for:PaymentRequest; text:[[state]]

spec:remote-playback; type:dfn; text: remote playback device

spec:webidl

type:dfn; text:namespace

type:idl; text:long

type:idl; text:short

</pre>

<pre class='ignored-specs'>

spec: epub-34

spec: mathml-core

spec: svg2

</pre>

<pre class="anchors">

urlPrefix: https://www.rfc-editor.org/rfc/rfc9110.html; spec: rfc9110

url: #name-accept; type: http-header; text: Accept

</pre>

<style>

table.data {

text-align: left;

font-size: small;

}

</style>

<h2 id="basic-principles">Principles behind design of Web APIs</h2>

The Design Principles are directly informed by the ethical framework

set out in the Ethical Web Principles [[ethical-web-principles]].

These principles provide concrete practical advice

in response to the higher level ethical responsibilities

that come with developing the web platform.

<h3 id="priority-of-constituencies">Put user needs first (Priority of Constituencies)</h3>

If a trade-off needs to be made,

always put user needs above all.

Similarly, when beginning to design an API,

be sure to understand and document the user need that the API aims to address.

[The internet is for end users](https://tools.ietf.org/html/rfc8890):

any change made to the web platform has the potential to

[affect vast numbers of people](https://www.w3.org/TR/ethical-web-principles/#allpeople),

and may have a profound impact on any person's life. [[RFC8890]]

User needs come before the needs of web page authors,

which come before the needs of user agent implementors,

which come before the needs of specification writers,

which come before theoretical purity.

Like all principles,

this isn't absolute.

Ease of authoring affects how content reaches users.

User agents have to prioritize finite engineering resources,

which affects how features reach authors.

Specification writers also have finite resources,

and theoretical concerns reflect underlying needs of all of these groups.

See also:

* [The web should not cause harm to society](https://www.w3.org/TR/ethical-web-principles/#noharm)

* [The web must enhance individuals' control and power](https://www.w3.org/TR/ethical-web-principles/#control)

* [[RFC8890]]

<h3 id="safe-to-browse">It should be safe to visit a web page</h3>

When adding new features,

design them to preserve the user expectation

that visiting a web page is generally safe.

The Web is named for its hyperlinked structure.

In order for the web to remain vibrant,

users need to be able to expect that merely visiting any given link

won't have implications for the security of their computer,

or for any essential aspects of their [privacy](https://www.w3.org/TR/ethical-web-principles/#privacy).

For example, an API that allows any website to

[detect the use of assistive technologies](#do-not-expose-use-of-assistive-tech)

may make users of these technologies feel unsafe visiting unknown web pages,

since any web page may detect this private information.

If users have a realistic expectation of safety,

they can make informed decisions

between Web-based technologies and other technologies.

For example, users may choose to use a web-based food ordering page,

rather than installing an app,

since installing a native app is riskier than visiting a web page.

To work towards making sure the reality of safety on the web matches users' expectations,

we can take complementary approaches when adding new features:

* We can improve the user interfaces through which the Web is used

to make it clearer what users of the Web should (and should not) expect;

* We can change the technical foundations of the Web

so that they match user expectations of privacy;

* We can consider the cases where users would be better off

if expectations were higher,

and in those cases

try to change both technical foundations and expectations.

A new feature which introduces safety risks may still improve user safety overall,

if it allows users to perform a task more safely on a web page

than it would be for them to install a native app to do the same thing.

However, this benefit needs to be weighed against the common goal

of users having a reasonable expectation of safety on web pages.

See also:

* [Security and Privacy Self-Review](https://www.w3.org/TR/security-privacy-questionnaire/)

<h3 id="trusted-ui">Trusted user interface should be trustworthy</h3>

Consider whether new features impact trusted user interfaces.

Users depend on trusted user interfaces

such as the address bar, security indicators and permission prompts,

to understand who they are interacting with and how.

These trusted user interfaces must be able to be designed in a way

that enables users to trust [and verify](https://www.w3.org/TR/ethical-web-principles/#verify)

that the information they provide is genuine,

and hasn't been spoofed or hijacked by the website.

If a new feature allows untrusted user interfaces

to resemble trusted user interfaces,

this makes it more difficult for users to understand what information is trustworthy.

<p class="example">

For example, JavaScript {{alert()}} allows a page to show a modal dialog which looks like part of the browser.

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="user-intent" oldids="consent">Design for user intent</h3>

Use your API design to encourage websites to

meet user expectations when accessing potentially unsafe capabilities.

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.

Using such a feature should only be possible

if the user's expectation matches the feature's consequences

(e.g., the personal information it reveals or the state it changes).

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.

</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 the remaining risk.

However, people often can't make good decisions on

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:

<ul>

<li> **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.</li>

<li> **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.

APIs should include a way for sites to learn of the change in status.</li>

<li id="ask-understandable-questions"> **Ask questions people can understand.**

When a typical user reads the question about a feature,

they should immediately think of the associated risks.

The risks should also 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.</li>

<li> **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.</li>

</ul>

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.

<div class=note>

A browser is responsible for managing requests for permission.

Browsers will not be able to understand

precisely how a user's interaction with a site

might result in a reasonable expectation of a permission request.

The web platform provides sites with many ways

either to communicate purpose and intent,

or to employ deception and trickery.

The responsibility for clearly communicating intent is therefore shared

between the design of APIs,

user interface design in browsers,

and how websites are constructed.

It is preferable if respect for user intent

is a natural outcome

of following the simple, obvious, or default usage pattern for the API.

This principle only asks that API designs encourage

to construct sites that respect user intent.

</div>

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.

For example, if the user agent asks permission to reveal a piece of information via one API,

the same information shouldn't be available with no permission via a different API.

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.

See also:

* [The web is secure, and respects people's privacy](https://www.w3.org/TR/ethical-web-principles/#privacy)

* [Consent Principles](https://www.w3.org/TR/privacy-principles/#consent-principles)

* [Permissions](https://www.w3.org/TR/permissions/)

<h3 id="identity">Use identity appropriately in context</h3>

Give people [control](https://www.w3.org/TR/ethical-web-principles/#control)

over the identifying information about themselves

they are presenting in different contexts on the web,

and be transparent about it.

"Identity" is a complex concept that can be understood in many different ways.

It can refer to how someone presents or sees themselves, how they relate to other

people, groups, or institutions, and can determine how they behave

or how they are treated by others.

In web architecture, "identity" is often used as a shortcut

to refer to identifiers, and the information attached to them.

Features that use or depend on

identifiers and the attachment of data about a person

to that identifier carry privacy risks which

often reach beyond a single API or system.

This includes data that has been passively generated (for example,

about their behaviour on the web) as well as that which has been

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

Use short-lived, temporary identifiers

unless a persistent identifier is absolutely necessary.

<h3 id="devices-platforms">Support the full range of devices and platforms (Media Independence)</h3>

<!-- was "Media Independence" in the HTML Design Principles -->

As much as possible,

ensure that features on the web work across different input and output [devices,

screen sizes, interaction modes, platforms, and media](https://www.w3.org/TR/ethical-web-principles/#multi).

One of the main values of the Web is that it's extremely flexible:

a Web page may be viewed on virtually any consumer computing device

at a very wide range of screen sizes,

may be used to generate printed media,

and may be interacted with in a large number of different ways.

New features should match the [existing flexibility](https://www.w3.org/TR/ethical-web-principles/#render)

of the web platform.

<div class="note">

This doesn't imply that features which don't work in *every* possible context should be excluded.

For example, hyperlinks can't be visited when printed on paper,

and the ''click'' event doesn't translate perfectly to touch input devices

where positioning and clicking the pointer occur in the same gesture (a "tap").

These features still work across a wide variety of contexts,

and can be adapted to devices that don't support their original intent -

for example, a tap on a mobile device will fire a ''click'' event as a fallback.

</div>

Features should also be designed so that the easiest way to use them

maintains flexibility.

<div class="example">

The 'display: block',

'display: flex',

and 'display: grid' layout models in CSS

all default to placing content within the available space and without overlap,

so that it works across screen sizes,

and allows users to choose their own font and font size without causing text to overflow.

</div>

Sometimes features aren't yet available on some implementations or platforms

despite working on others.

In these cases, features should be designed such that it is possible for

code to gracefully fail or be polyfilled.

See [[#feature-detect]].

<h3 id=new-features>Add new capabilities with care</h3>

Add new capabilities to the web with consideration of existing functionality and content.

The Web includes many extension points that allow for additions;

see for example [[HTML#extensibility]].

Before adding items, consider integration with existing, similar capabilities.

If this leads to a preferred design approach that cannot be implemented by only adding items,

it might still be possible; see [[#removing-features]].

Do not assume that a change or removal is impossible without first checking.

<h3 id=removing-features>Prioritize compatibility when changing or removing features</h3>

Before changing how a feature behaves,

understand how websites are currently using it.

Gaining a good understanding might require research,

for example by adding metrics to a widely-used user agent

or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/).

Breaking content harms users,

and the benefit of a change has to

significantly outweigh that harm to be worth doing

[[the-web-is-unversioned]].

The obligation to understand existing usage

also applies to non-standardized or unspecified features

that content relies upon.

This includes vendor-proprietary features and

implementation bugs.

Despite this, it is sometimes acceptable

to break some existing content

in order to improve the experience for a large number of web users.

Breakage is more likely to be acceptable if:

* Only a tiny amount of existing content depend on the feature or behavior.

* Only a tiny number of people see that content.

* The content appears only in test cases or examples.

* The content is already broken in some widely-used user agents,

and either they have not received many bug reports about it,

or the change is expected to improve interoperability.

* The benefit of breaking content is very large.

For example, removing old SSL and TLS versions caused a number of sites to become unreachable

but prevents more security breaches.

<h3 id="leave-the-web-better">Leave the web better than you found it</h3>

As you add new capabilities to the web platform,

do so in a way that improves the overall platform.

The existence of a defect in one part of the platform

must not be used to excuse an addition or extension to the defect,

which would further decrease the overall platform quality.

Consistency with existing problematic design patterns

is not a good reason to propagate those patterns

in newly specified Web APIs or platform features.

Where possible, build new web capabilities that improve the overall platform quality

by mitigating existing defects.

Do not extend a platform feature that has known defects,

without considering how to address those defects.

It is not necessary to completely fix existing problems,

but some attempt to address flaws is expected

when extending a feature with known issues.

This way, new or increased usage does not result in

increasing the harm that the defect might cause.

Parts of the web platform evolve independently.

Issues that are present with a certain web technology now may be fixed in a subsequent iteration.

Duplicating these issues makes fixing them more difficult.

By adhering to this principle we can make sure overall platform quality improves over time.

<h3 id="data-minimization">Minimize user data</h3>

Design features to work with the minimum amount of data necessary to carry out their

users' goals.

<a href="https://www.w3.org/TR/privacy-principles/#data-minimization">Data minimization</a>

limits the risks of data being inappropriately disclosed or misused.

Design Web APIs to make it easier for sites to request, collect, and/or transmit

a small amount of data, or more granular or specific data, than it is to work with

more generic or bulk data.

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

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

</div>

<h2 id="api-across-languages">API Design Across Languages</h2>

<h3 id="simplicity">Prefer simple solutions</h3>

<!-- was "Avoid Needless Complexity" in the HTML Design Principles -->

Look hard for simple solutions to the

<a href="#priority-of-constituencies">user needs</a>

you intend to address.

Simple solutions are generally better than complex solutions,

although they may be harder to find.

Simpler features are easier for user agents to implement and test,

more likely to be interoperable,

and easier for authors to understand.

It is especially important to design your feature so that

the most common use cases are easy to accomplish.

Make sure that your <a href="#priority-of-constituencies">user needs</a>

are well-defined.

This allows you to avoid scope creep,

and make sure that your API does actually meet the needs of all users.

Of course,

complex or rare use cases are also worth solving,

though their solutions may be more complicated to use.

As Alan Kay said,

"simple things should be simple, complex things should be possible."

Do note however that while common cases are often simple,

commonality and complexity are not always correlated.

<div class=example>

Sanitizing HTML to prevent XSS attacks is a complex process

that requires extensive security knowledge,

however the [Sanitizer API](https://wicg.github.io/sanitizer-api/) provides a shortcut for this common use case.

It also permits simpler types of filtering, but with more configuration.

</div>

See also:

* [[LEAST-POWER]]

<h3 id="high-level-low-level">Consider tradeoffs between high level and low level APIs</h3>

<!--

See "High level or low-level APIs?"

https://github.com/w3ctag/design-principles/issues/117

-->

High-level APIs allow user agents more ability to

intervene in various ways [on behalf of the user](#priority-of-constituencies),

such as to ensure accessibility, privacy, or usability.

<div class=example id=font-enumeration>

A font picker (high level API)

[was recommended by the TAG](https://github.com/w3ctag/design-reviews/issues/399)

over a Font Enumeration API (low level API)

as it addresses the bulk of use cases,

while preserving user privacy,

as it is free from the fingerprinting concerns that accompany

a general Font Enumeration API.

A native font picker also comes with accessibility built-in,

and provides consistency for end users.

</div>

Low-level APIs afford authors room for experimentation

so that high level APIs can organically emerge

from usage patterns over time.

They also provide an escape hatch when the higher-level API

is not adequate for the use case at hand.

Lower level building blocks cannot always be exposed as Web APIs.

A few possible reasons for this are

to preserve the user's security and privacy,

or to avoid tying Web APIs to specific hardware implementations.

However, high level APIs should be designed in terms of

building blocks over lower level APIs

whenever possible.

This may guide decisions on how high level the API needs to be.

A well-layered solution should ensure continuity

of the ease-of-use vs power tradeoff curve

and avoid sharp cliffs

where a small amount of incremental use case complexity

results in a large increase of code complexity.

<h3 id="name-thoughtfully">Name things thoughtfully</h3>

Name APIs with care.

Naming APIs well makes it much easier for authors to use them correctly.

See the more detailed <a href="#naming-is-hard">Naming principles</a> section

for specific guidance on naming.

<h3 id="consistency">Be consistent</h3>

It is good practice to consider precedent in the design of your API

and to try to be consistent with it.

There is often a tension between API ergonomics and consistency,

when existing precedent is of poor usability.

In some cases it makes sense to break consistency to improve usability,

but the improvement should be very significant to justify this.

<!-- TODO: example? -->

Since the web platform has gradually evolved over time,

there are often multiple conflicting precedents

which are mutually exclusive.

You can weigh which precedent to follow by taking into account

prevalence (all else being equal, follow the more popular precedent),

API ergonomics (all else being equal, follow the more usable precedent),

and API age (all else being equal, follow the newer precedent).

<!-- TODO: example? -->

There is often a tension between internal and external consistency.

<em>Internal consistency</em> is consistency with the rest of the system,

whereas <em>external consistency</em> is consistency with the rest of the world.

In the web platform, that might materialize in three layers:

consistency within the technology the API belongs to (e.g. CSS),

consistency with the rest of the web platform,

and in some cases external precedent,

when the API relates to a particular specialized outside domain.

In those cases, it is useful to consider what the majority of users will be.

Since for most APIs the target user is someone who is familiar with the

technology they are defined in,

err on the side of favoring consistency with that.

<div class="example">

One example is

<a href="https://www.w3.org/TR/css-color-4/#funcdef-lab">CIE L\*a\*b\* colors</a>:

It would be more consistent with the rest of CSS to use percentages for L (0%-100%),

but more consistent with the rest of Color Science to use a unitless number (0-100).

There was a lot of heated debate,

which resolved in favor of percentages,

i.e. consistency within CSS.

</div>

There is also a separate section on <a href="#naming-consistency">naming consistency</a>.

<h3 id="specs-include-guidance">Follow guidance from feature specifications</h3>

When using a feature,

follow guidance in the specification for that feature.

Specifications for features

that will be used by other specifications

should include guidance for using those features.

This ensures that the feature is used correctly

and consistently

throughout the platform.

An incomplete list of such guidance follows:

* [[encoding#specification-hooks|Encoding]]

* [[fetch#fetch-elsewhere|Fetch]]

* <span id="using-http">[[RFC9205 inline]]</span>,

especially on [[RFC9205#section-4.7|defining header fields]],

[other HTTP RFCs](https://datatracker.ietf.org/doc/search?name=HTTP&sort=&rfcs=on&by=group&group=httpbis),

and the [HTTP Working Group style guide](https://httpwg.org/admin/editors/style-guide)

* [[hr-time#sec-tools|Time]]

* [[url#url-apis-elsewhere|URLs]]

Consult with the relevant community

when using their specification.

This informs that community about new usage

and creates opportunities for improvements

to both the using and used specifications.

<h3 id="feature-detect">New features should be detectable</h3>

Provide a way for authors to programmatically detect

whether your feature is available,

so that web content may gracefully handle the feature not being present.

An existing feature may not be available on a page for a number of reasons.

Two of the more common reasons are

because it hasn't been implemented yet, or

because it's only available in <a href="#secure-context">secure contexts</a>.

Authors shouldn't need to write different code to handle each scenario.

That way, even if an author only knows or cares about one scenario,

the code will handle all of them.

<p class="note">

When a feature is available but isn't feasible to use

because a required device isn't present,

it's better to expose that the feature is available

and have a separate way to detect that the device isn't.

This allows authors to handle a device not being available differently

from the feature not being available,

for example by suggesting the user connect or enable the device.

See [[#device-enumeration]].

</p>

Authors should always be able to detect a feature from JavaScript,

and in some cases the feature should also be detectable

in the language where it's used

(such as ''@supports'' in CSS).

In some cases, it may **not** be appropriate to allow feature detection.

Whether the feature should be detectable or not

should be based on the <a href="#priority-of-constituencies">user need</a>

for the feature.

If there is a user need or design principle which would fail

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 [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

in order to enable denying requests to use the feature.

Also, if a feature is generally not exposed to developers,

it is not appropriate to support feature detection.

For example, private browsing mode is a concept

which is recognised in web specifications,

but not exposed to authors.

For private browsing mode to support the user's needs,

it must not be feature detected.

See also:

* [[#do-not-expose-use-of-private-browsing-mode]]

* [[#do-not-expose-use-of-assistive-tech]]

* [[#secure-context]]

* [[#user-decisions]]

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

Design textual formats that can be easily produced and consumed by people.

Textual formats also improve [transparency](https://www.w3.org/TR/ethical-web-principles/#transparent).

Favor readability over compactness.

File size can be optimized by tooling,

and tends to become a lower priority over time.

When file size is a significantly higher priority,

perhaps a textual format is not appropriate.

<div class=example>

SVG path syntax was designed to be compact,

with single-letter commands and unlabeled series of coordinates after them.

At the time, file size was a primary concern,

but while the importance of size efficiency has declined over time,

the cost to human readability has remained the same.

</div>

People who are presented with a textual format

should be able to use a text editor

to easily produce or modify content.

People who edit text will introduce a range of errors, but

could struggle to identify and fix those errors.

People expect some amount of flexibility in terms of how their edits are processed.

[[#avoid-ambiguity|Clearly defining]] syntactic flexibility--

such as in whitespace, quoting, or delimiters--

could ensure that content is both easy to edit and produces consistent results.

<div class=example>

The JSON format is an example of a format that appears to be flexible,

but it lacks many of these basic usability amenities.

In JSON there is:

no commenting capability,

objects and arrays cannot have trailing commas, and

quotes are mandatory for object keys.

This makes JSON prone to syntactic errors as a result of manual edits.

</div>

Containing the scope of a format that is affected by a syntax error

could improve robustness and human usability.

This requires that specifications fully define processing and

error handling so that all inputs result in consistent outcomes.

<div class=example>

Typos in CSS properties only cause that property to be ignored.

Errors in properties rarely cause an entire rule to be lost.

</div>

If your format is intended to be used only by machines,

a binary format is likely to be more efficient,

in addition to discouraging people from authoring or editing content directly.

<h3 id="secure-context">Consider limiting new features to secure contexts</h3>

Always limit your feature to secure contexts

if it would pose a risk to the user

without the authentication, integrity, or confidentiality

that's present only in secure contexts.

<div class="example">

One example of a feature that should be limited to secure contexts

is [Geolocation](https://www.w3.org/TR/geolocation-API/),

since it would be a risk to users' privacy to transmit their location in an insecure way.

</div>

For other features, TAG members past and present

haven't reached consensus on general advice.

Some believe that all new features

(other than features which are additions to existing features)

should be limited to secure contexts.

This would help encourage the use of HTTPS,

helping users be more secure in general.

Others believe that features should only be limited to secure contexts

if they have a known security or privacy impact.

This lowers the barrier to entry for creating web pages

that take advantage of new features which don't impact user security or privacy.

<div class="note">

Specification authors can limit most features defined in

Web IDL [[WEBIDL]],

to secure contexts

by using the

[{{SecureContext}}] extended attribute

on interfaces, namespaces, or their members (such as methods and attributes).

However, for some types of API (e.g., dispatching an event),

limitation to secure contexts should just

be defined in normative prose in the specification.

If this is the case,

consider whether there might be scope for adding a similar mechanism

to [{{SecureContext}}]

to make this process easier for future API developers.

</div>

<div class="note">

As described in [[#feature-detect]],

you should provide a way to programmatically detect whether a feature is available,

including cases where the feature is unavailable because the context isn't secure.

However, if, for some reason

there is no way for code to gracefully handle the feature not being present,

limiting the feature to secure contexts might cause problems

for code (such as libraries) that may be used in either secure or non-secure contexts.

</div>

<h3 id="do-not-expose-use-of-private-browsing-mode">Don't reveal that private browsing mode is engaged</h3>

Make sure that your feature doesn't give authors a way to detect private browsing mode.

Some people use [private browsing mode](https://www.w3.org/2001/tag/doc/private-browsing-modes/)

to protect their own personal safety.

Because of this, the fact that someone is using private browsing mode

may be [sensitive information](https://www.w3.org/TR/security-privacy-questionnaire/#sensitive-data) about them.

This information may [harm](https://www.w3.org/TR/ethical-web-principles/#noharm) people

if it is revealed to a web site controlled by others who have power over them

(such as employers, parents, partners,

or [state actors](https://www.w3.org/TR/ethical-web-principles/#expression)).

Given such dangers,

websites should not be able to detect that private browsing mode is engaged.

<div class="example">

User Agents which support [IndexedDB](https://www.w3.org/TR/IndexedDB/)

should not disable it in private browsing mode,

because that would reveal that private browsing mode is engaged

</div>

<div class="example">

The [Payment Request API](https://www.w3.org/TR/payment-request/)'s

[show() method](https://www.w3.org/TR/payment-request/#show-method),

when called,

allows User Agents <q cite="https://www.w3.org/TR/payment-request/#show-method">to act

as if the user had immediately

[aborted the payment request](https://www.w3.org/TR/payment-request/#dfn-user-aborts-the-payment-request)</q>.

This enables User Agents to automatically abort payment requests

in private browsing mode

(thus protecting [sensitive information](https://www.w3.org/TR/security-privacy-questionnaire/#sensitive-data)

such as the user's shipping or billing address)

without revealing that private browsing mode is engaged.

</div>

See also:

* [Security and privacy are essential](https://www.w3.org/TR/ethical-web-principles/#privacy)

* [What data does this specification expose to an origin?](https://www.w3.org/TR/security-privacy-questionnaire/#underlying-platform-data)

* [[#private-browsing-mode]]

<h3 id="private-browsing-mode">Consider how your API should behave in private browsing mode</h3>

If necessary, specify how your API should behave differently

in private browsing mode.

For example, if your API would reveal information

that would allow someone to correlate

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 [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.

Therefore, APIs which provide client-side storage

should not persist data stored

while private browsing mode is engaged

after it's disengaged.

This can and should be done

without revealing any detectable API differences to the site.

<div class="example">

User Agents which support

[localStorage](https://html.spec.whatwg.org/multipage/webstorage.html#dom-localstorage)

should not persist storage area changes

made while private browsing mode is engaged.

If the User Agent has two simultaneous sessions with a site,

one in private browsing mode and one not,

storage area changes made in the private browsing mode session

should not be revealed to the other browsing session,

and vice versa.

(The [storage event](https://html.spec.whatwg.org/multipage/indices.html#event-storage) should not be fired

at the other session's [window object](https://html.spec.whatwg.org/multipage/window-object.html#window).)

</div>

See also:

* [[#do-not-expose-use-of-private-browsing-mode]]

* [Does this specification introduce new state for an origin that persists across browsing sessions?](https://www.w3.org/TR/security-privacy-questionnaire/#persistent-origin-specific-state)

* [Security and privacy self review: Private Browsing](https://www.w3.org/TR/security-privacy-questionnaire/#private-browsing)

<h3 id="do-not-expose-use-of-assistive-tech">Don't reveal that assistive technologies are being used</h3>

Make sure that your API doesn't provide a way

for authors to detect that a user is using assistive technology.

[The web platform must be accessible to people with disabilities.](https://www.w3.org/TR/ethical-web-principles/#allpeople)

If a site can detect that a user is using an assistive technology,

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/TR/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,

this sensitive information may be revealed to others

(including [state actors](https://www.w3.org/TR/ethical-web-principles/#expression))

who may wish them harm.

Sometimes people propose features which aim to improve the user experience

for users of assistive technology,

but which would reveal the user's use of assistive technology as a side effect.

While these are well intentioned,

they violate [[#safe-to-browse]],

so alternative solutions must be found.

<div class="example">

The [Accessibility Object Model](https://wicg.github.io/aom/) (AOM)

used to define a set of events which, when fired,

[revealed the use of assistive technology](https://github.com/WICG/aom/issues/81).

AOM has since removed these events and

[replaced them](https://github.com/WICG/aom/blob/gh-pages/explainer.md#user-action-events-from-assistive-technology) with synthetic DOM events

which don't reveal the use of assistive technology.

</div>

See also:

* [Web Technology Accessibility Guidelines](https://w3c.github.io/apa/fast/)

* [Security and privacy are essential](https://www.w3.org/TR/ethical-web-principles/#privacy)

* [What data does this specification expose to an origin?](https://www.w3.org/TR/security-privacy-questionnaire/#underlying-platform-data)

<h3 id="require-user-activation">Require user activation for powerful APIs</h3>

Some powerful APIs can produce intrusive UI (eg. auto-playing audio),

expose user data (eg. interacting with the clipboard),

perform a background activity without an obvious indicator to the user (eg. accessing local storage),

or prompt the user to interact with [trusted UI](#trusted-ui)

(eg. permission prompts, device hardware features).

These APIs should be designed to require some indication of user intention (such as **user activation**) in order to function.

This indicates that the user is intentionally interacting with the web page in question.

User activation is defined in detail

[in the HTML standard](https://html.spec.whatwg.org/#tracking-user-activation).

You should think about the effect your API has on the user experience,

as well as any risks presented to the user,

when deciding whether user activation needs to only occur

once overall ([sticky](https://html.spec.whatwg.org/#sticky-activation-gated-api)),

periodically ([transient](https://html.spec.whatwg.org/#transient-activation-gated-api)) or

once per API call ([transient consuming](https://html.spec.whatwg.org/#activation-consuming-api)).

Note that while user activation is in many cases necessary,

it is not always *sufficient*

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="handle-non-fully-active-documents">Handle non-fully-active documents</h3>

Make sure that your API behaves predictably

when its [=relevant global object=]'s [=associated Document=]

is no longer [=Document/fully active=].

Fail fast when the document is already non-[=Document/fully active=]

and abort cleanly if it becomes non-[=Document/fully active=] mid-operation.

When an <{iframe}> (or similar) is removed or navigated,

its [=associated Document=] can stop being [=Document/fully active=].

In many cases, user agents will tear down the document’s JavaScript

[=ECMAScript/execution contexts=] rather than keeping them suspended.

However, references to objects from that document

can remain reachable from other documents

or from other parts of the user agent.

This situation can arise when browser-mediated UI

(e.g., authentication, payment, or credential presentation)

is shown on behalf of an <{iframe}>

and the <{iframe}> is removed or navigated

while a user is interacting with that interface.

Specifications must define how calls and UI actions

interact with non-[=Document/fully active=] documents

both at call time

and after an operation has begun.

Doing so helps ensure that background work stops

on non-[=Document/fully active=] documents,

that user-facing UI is gracefully dismissed,

and that user agents behave consistently.

As general rules:

* If, at call time,

the [=relevant global object=]'s [=associated Document=]

is not [=Document/fully active=],

then the operation must fail immediately.

We suggest using an {{InvalidStateError}} {{DOMException}}.

* If, after starting an asynchronous operation,

the [=associated Document=] becomes non-[=Document/fully active=],

the operation must be aborted

and failure signaled with {{AbortError}}.

If the operation presents user-facing UI

(e.g., a picker, chooser, or prompt),

dismiss it when the document becomes non-[=Document/fully active=]

and settle with {{AbortError}}.

When [=queue a task|queueing=] subsequent work

(for example, to dispatch an event,

settle a promise, or perform time-based processing),

specifications should include an early-exit check

at the point the [=task=] runs:

if the [=associated Document=] is not [=Document/fully active=],

then gracefully terminate the [=task=]

without further observable effects.

Specifications must not rely on garbage collection

to define these semantics.

See also: [[#support-non-fully-active]] for the BFCache case.

Many of the same principles apply to detached iframes

and other documents that have become non-[=Document/fully active=],

even though BFCache may suspend a document

rather than tearing it down.

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

Specify how your feature behaves