From e2526faa15a85a01c12006fefd33d2aadb620d0e Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Date: Sat, 2 May 2026 17:21:06 +0530 Subject: [PATCH 1/2] Refine documentation for DD. --- destinations/index.html | 91 ++++++++++++++++++------- explainers/discoverable-destinations.md | 86 ++++++++++++++++++----- 2 files changed, 133 insertions(+), 44 deletions(-) diff --git a/destinations/index.html b/destinations/index.html index 61b8c64..3955249 100644 --- a/destinations/index.html +++ b/destinations/index.html @@ -78,9 +78,6 @@

Out of scope

Use Cases and Requirements

-
-

This section needs some work.

-

User research

Our proposed "discoverable destinations" come from work done by the User research that the WAI-Adapt TF inherited from COGA.

An illustrative set of proposed discoverable destinations is as -follows...

+follows.

+

Use Cases

+

The following use cases illustrate the kinds of navigation challenges that Discoverable Destinations are intended to address.

+ +

Accessibility Statement Discovery

+

An accessibility auditor is reviewing a portfolio of websites on behalf of a disability rights organization. Each site structures its accessibility statement differently, some link to it from the footer, others from the main navigation, and others only from an internal policy page. The auditor spends considerable time on each site searching for the relevant page before the audit can begin.

+

With Discoverable Destinations, a User Agent or assistive technology can immediately locate the accessibility-statement destination on any compliant site and present a direct link to the auditor, regardless of where the site has chosen to place it in its navigation structure.

+ +

Navigation Support for Users with Cognitive Disabilities

+

A user with a cognitive disability wants to log in to their account on a retail website. The site's primary navigation does not label the login entry point in a way the user recognises, and the page layout makes it difficult to locate. The user's browser extension, which presents a simplified navigation panel, cannot automatically locate the login page because no standard signposting exists.

+

With Discoverable Destinations, the browser extension can read the log-in destination from the page's <head> and present a clearly labelled button in its simplified interface, giving the user a direct and reliable path to the page they need.

+ +

AI Agent Assistance

+

A user with motor impairments uses an AI-powered assistive agent to help navigate websites and complete common tasks. The user asks the agent to "find the help page for my internet provider." Without semantic signposting, the agent must attempt to locate the help page by guessing at URL structures or parsing navigation HTML, which is brittle and may fail when the site is updated.

+

With Discoverable Destinations, the agent can query the help destination directly from the site's page headers, retrieve the correct URL in a single step, and navigate the user there reliably, regardless of how the site has structured its navigation menus.

+ +

Password Change Assistance

+

A password manager application wants to help users navigate directly to the password change page on any website, consistent with the Well-Known URL for Changing Passwords specification. On many sites, the password change page is buried several levels deep within account settings, and its location varies across sites.

+

With Discoverable Destinations, the password manager can use the change-password destination to locate the correct page directly, without the need for site-specific integration or manual maintenance of URL mappings.

+

Technical requirements

Any approach that addresses these user needs must provide the following.

@@ -228,27 +244,40 @@

Demarcating destination content

Open Questions

-
-

The sub-sections here should be promoted, and match the numbers of the corresponding technical requirements above. Some requirements should be added to that list in order to provide the justification for those requirements being addressed in this section.

-

Indicating the kind of content

+

The current approach identifies where a destination is located but does not convey what kind of support or content it provides. This distinction is important for users with cognitive disabilities who may require a specific mode of interaction. For example, a user may need to speak to a human being over the phone rather than engage with a chatbot or submit a form by email.

+

Several possible approaches are under consideration:

+
-

As above, COGA need that we are not yet addressing.

+

We still need to find reasonable resolution for above problem. We may also delay the resolution till next iteration

+

Discoverability and repetition

-
-

This is a work-in-progress

-
+

The current approach requires all <link> destination elements to be repeated in the <head> of every page on the site. This has the advantage of simplicity, a User Agent can read the available destinations from the current page without making any additional HTTP requests. However, it introduces authoring overhead and requires every page to be updated whenever a destination URL changes.

+

The Task Force has agreed to adopt the <link> element approach for the first iteration of this specification. This decision reflects that the approach has a low entry barrier, as it builds on existing, well-understood HTML mechanisms that content authors and User Agents already support, requires no new infrastructure, and can be incrementally adopted. The per-page repetition, while an authoring overhead, can be managed in practice through CMS templates.

+

The following questions remain open for future iterations:

+ +

The Linksets format offers one possible path toward centralized discovery and may be revisited in a subsequent iteration.

+

Demarcating sub-sites

-
-

This is a work-in-progress

-
+

A site hosted at a single origin may contain functionally distinct sub-sites. For example, a hotel website might host a main booking section, a restaurant section, and a gym section, each with its own set of relevant destinations.

+

The <link> element approach handles this naturally. Because every page carries its own <link> declarations, each sub-site simply includes the destinations relevant to that sub-site on its pages. The User Agent always reads the destinations from the current page, so:

+

The Task Force considers sub-site demarcation to be resolved by the per-page <link> approach.

@@ -296,18 +325,18 @@

Integration Patterns

Requesting Additional Destination Types

-
-

This section is a placeholder. The process for requesting standardisation of additional destination types is to be defined.

-
-

The set of standardised destination types may evolve over time as new common navigation patterns emerge. Parties interested in proposing additional destination types should consider the following:

+

The set of standardised destination types may evolve over time as new common navigation patterns emerge and as new user needs are identified. The current set of destinations reflects the priorities identified by the COGA TF at the time of publication, but it is not exhaustive.

+

Parties interested in proposing additional destination types should consider the following criteria:

    -

  • The proposed destination type should address a common navigation need that is shared across many websites.

    • +

  • The proposed destination type should address a common navigation need that is shared across many websites, not a need specific to a particular industry or platform.

  • The destination type should provide clear accessibility benefits, particularly for users facing cognitive accessibility barriers.

    • -

  • The destination type should be sufficiently general to apply across different industries and website types.

    • +

  • The destination type should be sufficiently general to apply across different industries and website types. Where a need is specific to a particular domain, it may be more appropriate to address it through domain-specific conventions rather than a standardised destination type.

    • +

  • The destination type should not duplicate an existing destination type or overlap significantly with one already in the standard.

-

The formal governance process for proposing, reviewing, and adding new destination types to the standard is under development.

+

The formal governance process for proposing, reviewing, and adding new destination types to the standard is under development. Interested parties are encouraged to raise proposals as issues in the WAI-Adapt GitHub repository for discussion by the Task Force.

+

For agentic AI use cases specifically, additional destination types may be beneficial in contexts where AI agents need reliable access to common site areas that are not yet covered by the current set. For example, account settings pages and accessibility preference pages. Proposals for such additions should follow the criteria above and be raised with the Task Force for review.

@@ -316,12 +345,14 @@

Privacy and Security Considerations

Privacy Considerations

Discoverable Destinations use standard HTML <link> elements that are already part of web pages. No additional user data is collected or transmitted beyond normal web browsing. The approach does not introduce any new tracking mechanisms, as User Agents discover destinations by parsing existing page content. Users retain full control over when and how they navigate to discovered destinations through the User Agent interface.

+

A User Agent that exposes a destination list to the user reveals which discoverable destinations a site supports. Since this information is already present in the page's <head> and therefore visible to any party that loads the page, no new information is disclosed by processing or presenting it.

Security Considerations

-

All navigation uses standard HTTP and HTTPS requests subject to normal browser security policies. Destinations are typically within the same origin, which reduces cross origin security concerns. Content authors are responsible for ensuring that the href values in their <link> elements point to legitimate, secure pages.

+

All navigation uses standard HTTP and HTTPS requests subject to normal browser security policies. Destinations are typically within the same origin, which reduces cross-origin security concerns. Content authors are responsible for ensuring that the href values in their <link> elements point to legitimate, secure pages under their control.

+

User Agents and extensions that implement a discoverable destination interface should validate that destination URLs share the same origin as the page from which they were discovered. Where a cross-origin destination URL is present, User Agents should present the full URL to the user before navigating, to support informed decision-making.

Considerations for AI Agent Integration

-

When AI agents use Discoverable Destinations on behalf of users, certain considerations apply. For sensitive operations such as authentication or account changes, human oversight should be maintained. Discoverable Destinations are designed for navigation and content discovery, not for executing complex authenticated operations. The primary approach for sensitive operations should be human in the loop, where AI agents navigate to relevant pages using semantic destinations, extract and present available options to users, then hand control to humans for actual execution.

+

When AI agents use Discoverable Destinations on behalf of users, the same privacy and security considerations apply as for human users. Additionally, agents should not aggregate or store destination metadata in ways that could be used to profile users' browsing patterns across sites. For sensitive operations such as authentication or account changes, human oversight should be maintained. Discoverable Destinations are designed for navigation and content discovery, not for executing complex authenticated operations. The primary approach for sensitive operations should be human-in-the-loop, where AI agents navigate to relevant pages using semantic destinations, extract and present available options to users, then hand control to humans for actual execution.

@@ -329,7 +360,7 @@

References

Foundational and Related Work

- + + + +
Acknowledgements placeholder
diff --git a/explainers/discoverable-destinations.md b/explainers/discoverable-destinations.md index 79e36ce..a183117 100644 --- a/explainers/discoverable-destinations.md +++ b/explainers/discoverable-destinations.md @@ -62,7 +62,7 @@ This specification aims to address the challenge of making sites more easily nav The User Agent, or a User Agent extension, could provide an interface to allow the user to: view supported common pages using a method, and terminology, that is clear to them; and to request to visit common destination pages directly. -This specification builds upon several existing specifications and registries, as detailed in the [foundational work](#foundational-work) section below. +This specification builds upon several existing specifications and registries, as detailed in the [foundational and related work](#foundational-and-related-work) section below. The motivating use cases, "option 1" approach (using Well-known URIs), and an example end-user UI, are depicted in [our Discoverable Destinations AC 2024 lightning talk](https://w3c.github.io/adapt/presentations/ac2024/). @@ -84,7 +84,7 @@ The motivating use cases, "option 1" approach (using Well-known URIs), and an ex * Specifying the interface within the UA (or UA extension) by which the user can navigate to supported well-known pages. -Though detailed UI design is out of scope, an proof-of-concept UI for enumerating a site's discoverable destinations is depicted below. +Though detailed UI design is out of scope, a proof-of-concept UI for enumerating a site's discoverable destinations is depicted below. ![A fictional ACME Inc. home page, with the extension pop-up open, showing 6 buttons, each containing emoji and accompanying text names for the discoverable destinations offered by the site: home, accessibility statement, contact, help, log in, and products.](../presentations/ac2024/ext02.png) @@ -111,7 +111,7 @@ An illustrative set of proposed discoverable destinations is as follows... ## Technical requirements -Any approch that would solve these user needs must provide the following. +Any approach that would solve these user needs must provide the following. * A way to represent each discoverable destination proposed above. @@ -197,37 +197,87 @@ When an in-page (anchor, ``) link points to a page that is a sub-page of a di As discoverable destinations are normal links, they can make use of fragments to point to certain elements on the destination page. +In addition to fragment identifiers, [ARIA landmark roles](https://www.w3.org/TR/wai-aria-1.2/#landmark_roles) provide a complementary mechanism for both identifying and navigating to content on a destination page. In particular, the `
` element (or `role="main"`) demarcates the principal content of the page. When a discoverable destination link does not include a fragment identifier, User Agents and assistive technologies should treat the `
` element as the default content boundary for the destination. Content authors are encouraged to ensure that destination pages use the `
` element to wrap their primary destination content. + +Landmarks also support navigation within a page. A destination page may contain multiple labelled `region` landmarks, each representing a distinct content area. User Agents and assistive technologies can enumerate these landmarks and present them to the user, or navigate directly to a specific region. For example, a help destination page with regions labelled "Getting Started", "Account Settings", and "Billing Support" would allow the user or their agent to jump directly to the relevant section. + The UA/AT can then use this information (and the knowledge that the navigation was via the Discoverable Destination UI) to render the destination page in an appropriate way for the user. This may involve: * Highlighting the specific relevant part of the page. -* Removing other elements from the rendering of the page. +* Removing other elements from the rendering of the page to reduce cognitive load. + +* Providing additional context or guidance based on the destination type. ## Open Questions ### Indicating the _kind_ of content -> [!NOTE] -> As above, COGA need that we are not yet addressing. +The current proposal identifies _where_ a destination is located but does not convey _what kind_ of support or content it offers. This distinction matters for users with cognitive disabilities who may need a specific type of interaction. For instance, a user may need to speak to a human being over the phone rather than engage with a chatbot or submit an email form. + +The question is whether, and how, such information should be expressed alongside or within a destination. Possible approaches include: + +* Extending the `rel` value vocabulary to include more specific destination subtypes (e.g. `help-human`, `help-chat`), though this risks combinatorial explosion as the number of content kinds grows. + +* Using an additional attribute or a companion `` element to annotate the kind of support offered by a given destination, keeping the destination identifier itself stable. + +* Deferring this concern to the destination page itself, where structured data (e.g. schema.org markup) could describe the available support types, leaving it to the UA to interpret and present this. + +This remains an open question under active consideration with the COGA Task Force. A resolution is expected to inform a future iteration of this work. ### Discoverability and repetition -> [!NOTE] -> This is a work-in-progress +The current approach requires all `` destination elements to be repeated in the `` of every page on the site. This has the advantage of simplicity, a UA can read the destinations of the current page without fetching any additional resource. However, it introduces authoring overhead, since every page must be regenerated whenever a destination URL changes. + +**The Task Force has agreed to adopt the `` element approach for the first cut of this specification.** This decision reflects that the approach is highly flexible, straightforward to implement by content authors and UAs alike, and builds directly on existing, well-understood HTML mechanisms. The per-page repetition, while an authoring overhead, can be managed in practice by modern CMS tooling. + +Several questions remain open for future iterations: + +* Should there be a single canonical discovery endpoint (such as a well-known URI) that a UA can consult once per origin, rather than reading destinations from each page? This would reduce per-page overhead but would require an extra HTTP request on first visit. + +* If a centralized endpoint is added, how should per-page and per-origin destinations be reconciled when they differ? For instance, a sub-site may legitimately override some destinations declared at the origin level. + +* What caching expectations should be set for destination declarations, both in the per-page `` approach and in any centralized discovery document? + +The [Linksets](#linksets) alternative described later in this document offers one possible path to centralized discovery and may be revisited in a subsequent iteration. ### Demarcating sub-sites -> [!NOTE] -> This is a work-in-progress +A site hosted at a single origin may contain functionally distinct sub-sites (for example, a hotel website that hosts both a main booking section and a restaurant section). Each sub-site may wish to declare its own set of destinations that differ from those of the root site. + +The `` element approach handles this naturally. Because every page carries its own `` declarations, each sub-site simply includes the destinations relevant to that sub-site on its pages. The UA always reads the destinations from the current page, so: + +* **Scope is implicit and automatic.** When the user is on a restaurant sub-site page, that page's `` elements define the applicable destinations. No boundary detection or URL prefix matching is required. + +* **Overriding destinations is straightforward.** A sub-site page that declares a different `contact` destination than the root site will naturally present the sub-site's destination to the UA, since the UA always uses the current page's declarations. -* Semantically +* **No additional authoring mechanism is needed.** Content authors control sub-site scoping by controlling which `` elements appear on each set of pages, typically managed through their CMS templates. -* UI-wise +The Task Force considers sub-site demarcation to be resolved by the per-page `` approach. ## Security \& Privacy considerations -> [!NOTE] -> We have not completed this section yet. +### Privacy + +Discoverable Destinations use standard HTML `` elements that are already part of web pages. No additional user data is collected or transmitted beyond normal web browsing. The approach does not introduce any new tracking mechanisms like User Agents discover destinations by parsing existing page content. Users retain full control over when and how they navigate to discovered destinations through the UA interface. + +A UA that exposes a destination list to the user reveals which discoverable destinations a site supports. Since this information is already present in the page's `` and therefore visible to any party that loads the page, no new information is exposed by processing or displaying it. + +### Security + +All navigation triggered by discoverable destinations uses standard HTTP and HTTPS requests, subject to normal browser security policies. Destination URLs are typically within the same origin as the page declaring them, which reduces cross-origin security concerns. + +Content authors are responsible for ensuring that the `href` values in their `` elements point to legitimate, secure pages under their control. A malicious or compromised CMS could inject destination `` elements pointing to phishing pages; however, this is not a new attack surface specific to this proposal. The same risk exists for any link or navigation element present in a page. + +UAs and UA extensions that implement a discoverable destination interface should validate that destination URLs share the same origin as the page from which they were discovered, and should present the full URL to the user before navigating, to support informed decision-making. + +### Considerations for AI Agents + +When AI agents use Discoverable Destinations on behalf of users, the same privacy and security considerations apply as for human users. Additionally: + +* Agents should not aggregate or store destination metadata in ways that could be used to profile users' browsing patterns across sites. + +* For sensitive operations such as authentication or account changes, human oversight should be maintained. Discoverable Destinations are designed for navigation and content discovery, not for executing complex authenticated operations. ## Alternatives considered @@ -312,7 +362,7 @@ The first time the user visits the origin, the linkset for the origin, and sub-s A linkset document (i.e. the JSON serialization) would be created for the site. -For example, the linkset for a simple site (with no sub-sites), which supports three well-known destinatiions (`accessibility-statement`, `help`, and `log-in`), may be represented as follows. +For example, the linkset for a simple site (with no sub-sites), which supports three well-known destinations (`accessibility-statement`, `help`, and `log-in`), may be represented as follows. ```json { "linkset": @@ -334,7 +384,7 @@ For example, the linkset for a simple site (with no sub-sites), which supports t Note that the linkset standard allows us to provide links to equivalent pages in other human languages; this is not shown here, for brevity. -Also note that a **UA that supports discoverable destinations would interpret the `anchor` field in a specific way:** Discoverable Destinations are intented to be (sub-)site-wide, so the links relating to the single given `anchor` above would apply to all other URLs that start with the `anchor`'s URL. +Also note that a **UA that supports discoverable destinations would interpret the `anchor` field in a specific way:** Discoverable Destinations are intended to be (sub-)site-wide, so the links relating to the single given `anchor` above would apply to all other URLs that start with the `anchor`'s URL. A more complex site, which is hosted at one origin, but provides two micro-sites, could be coded as follows. The following example linkset represents a hotel's website that has the following structure. @@ -398,7 +448,7 @@ The content author would need to update the linkset file, and replace it on the A link could be decorated with a `rel` attribute value that corresponds to the applicable destination. -The UA will know if this link points to the root of the discoverable destination (e.g. the "Help" landing page, vs "Help on logging in") becuase it knows the URL of the root of the discoverable destination, via the discovery process above. +The UA will know if this link points to the root of the discoverable destination (e.g. the "Help" landing page, vs "Help on logging in") because it knows the URL of the root of the discoverable destination, via the discovery process above. #### Demarcating destination content @@ -443,7 +493,7 @@ The UA will know if this link points to the root of the discoverable destination - [Link types managed by the Microformats project](https://html.spec.whatwg.org/multipage/links.html#other-link-types) - - [Link types anaged by IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml) + - [Link types managed by IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml) #### Linksets From ea4359a29bec44e6cda6b05fc8d05ba60a7a92a5 Mon Sep 17 00:00:00 2001 From: Abhinav Kumar Date: Mon, 29 Jun 2026 14:53:42 +0530 Subject: [PATCH 2/2] Feedback incorporation. --- destinations/index.html | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/destinations/index.html b/destinations/index.html index 3955249..81d8a20 100644 --- a/destinations/index.html +++ b/destinations/index.html @@ -112,21 +112,21 @@

User research

Use Cases

The following use cases illustrate the kinds of navigation challenges that Discoverable Destinations are intended to address.

+

Navigation Support for Users with Cognitive Disabilities

+

A user with a cognitive disability wants to find common areas of a website, such as help pages, contact information, or their account login. The site's navigation uses unfamiliar labels, buries key pages in dropdown menus, or presents a complex layout that makes it difficult to locate these areas. Without standard signposting, User Agents and assistive technologies have no reliable way to identify these pages on the user's behalf.

+

With Discoverable Destinations, a User Agent can read standardised destination identifiers from the page's <head> and present clearly labelled navigation options in an accessible and consistent interface, giving the user direct and reliable paths to the pages they need, regardless of how the site has chosen to structure its navigation.

+

Accessibility Statement Discovery

An accessibility auditor is reviewing a portfolio of websites on behalf of a disability rights organization. Each site structures its accessibility statement differently, some link to it from the footer, others from the main navigation, and others only from an internal policy page. The auditor spends considerable time on each site searching for the relevant page before the audit can begin.

With Discoverable Destinations, a User Agent or assistive technology can immediately locate the accessibility-statement destination on any compliant site and present a direct link to the auditor, regardless of where the site has chosen to place it in its navigation structure.

-

Navigation Support for Users with Cognitive Disabilities

-

A user with a cognitive disability wants to log in to their account on a retail website. The site's primary navigation does not label the login entry point in a way the user recognises, and the page layout makes it difficult to locate. The user's browser extension, which presents a simplified navigation panel, cannot automatically locate the login page because no standard signposting exists.

-

With Discoverable Destinations, the browser extension can read the log-in destination from the page's <head> and present a clearly labelled button in its simplified interface, giving the user a direct and reliable path to the page they need.

- -

AI Agent Assistance

-

A user with motor impairments uses an AI-powered assistive agent to help navigate websites and complete common tasks. The user asks the agent to "find the help page for my internet provider." Without semantic signposting, the agent must attempt to locate the help page by guessing at URL structures or parsing navigation HTML, which is brittle and may fail when the site is updated.

-

With Discoverable Destinations, the agent can query the help destination directly from the site's page headers, retrieve the correct URL in a single step, and navigate the user there reliably, regardless of how the site has structured its navigation menus.

+

Assistive Navigation Technology

+

A user with motor impairments uses assistive navigation technology, such as speech recognition or switch access software, to browse websites and complete common tasks. The user asks to "go to the help page" but the software cannot reliably identify the correct link because sites label and position their help pages inconsistently. Without semantic signposting, the software must attempt to locate the page by guessing at link text or URL structures, which is brittle and may fail when the site is updated.

+

With Discoverable Destinations, assistive navigation technology can query the help destination directly from the site's page headers, retrieve the correct URL in a single step, and navigate the user there reliably, regardless of how the site has structured its navigation menus.

-

Password Change Assistance

-

A password manager application wants to help users navigate directly to the password change page on any website, consistent with the Well-Known URL for Changing Passwords specification. On many sites, the password change page is buried several levels deep within account settings, and its location varies across sites.

-

With Discoverable Destinations, the password manager can use the change-password destination to locate the correct page directly, without the need for site-specific integration or manual maintenance of URL mappings.

+

Agent-based Navigation

+

An agent is navigating a website headlessly on behalf of a user, for example to gather information or complete a routine task. Without standard signposting, the agent must rely on heuristics such as parsing navigation HTML or guessing URL patterns, approaches that are fragile and break when sites change their structure.

+

With Discoverable Destinations, the agent can programmatically discover standard page types from the site's <link> elements, enabling consistent and reliable navigation across any compliant site without site-specific configuration.

Technical requirements

Any approach that addresses these user needs must provide the