Skip to content

Refine documentation for DD #337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abhina-kumar wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Refine documentation for DD #337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
91 changes: 65 additions & 26 deletions destinations/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,6 @@ <h3 id="out-of-scope">Out of scope</h3>

<section>
<h2>Use Cases and Requirements</h2>
<div class=issue>
<p>This section needs some work.</p>
</div>

<h3 id="user-research">User research</h3>
<p>Our proposed "discoverable destinations" come from work done by the <a
Expand All @@ -93,7 +90,7 @@ <h3 id="user-research">User research</h3>
that the WAI-Adapt TF inherited from COGA</a>.</p>
</div>
<p>An illustrative set of proposed discoverable destinations is as
follows...</p>
follows.</p>
<ul>
<li><p><code>accessibility-statement</code> (for the site's <a
href="https://www.w3.org/WAI/planning/statements/">accessibility
Expand All @@ -112,6 +109,25 @@ <h3 id="user-research">User research</h3>
form)</p></li>
</ul>

<h3 id="use-cases">Use Cases</h3>
<p>The following use cases illustrate the kinds of navigation challenges that Discoverable Destinations are intended to address.</p>

<h4 id="use-case-accessibility-audit">Accessibility Statement Discovery</h4>
<p>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.</p>
<p>With Discoverable Destinations, a User Agent or assistive technology can immediately locate the <code>accessibility-statement</code> 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.</p>

<h4 id="use-case-cognitive-navigation">Navigation Support for Users with Cognitive Disabilities</h4>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We're primarily doing this work for this use case, so it should come first (and, maybe, be widened a bit).

<p>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.</p>
<p>With Discoverable Destinations, the browser extension can read the <code>log-in</code> destination from the page's <code>&lt;head&gt;</code> and present a clearly labelled button in its simplified interface, giving the user a direct and reliable path to the page they need.</p>

<h4 id="use-case-ai-agent">AI Agent Assistance</h4>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This actually to me seems like it's describing another accessibility use case. I would put this as a sub-section of the accessibility use cases, but I wouldn't reference AI agents here. This would apply to existing speech recognition based navigation technology, if it were updated to support it.

For the AI agents use case, I would say something a bit more general, like an agent that's navigating a site on behalf of a user (headlessly).

<p>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.</p>
<p>With Discoverable Destinations, the agent can query the <code>help</code> 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.</p>

<h4 id="use-case-password-change">Password Change Assistance</h4>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't think we can use this, as that spec uses well-known URIs. I think it adds too much confusion.

<p>A password manager application wants to help users navigate directly to the password change page on any website, consistent with the <a href="https://www.w3.org/TR/change-password-url/">Well-Known URL for Changing Passwords</a> specification. On many sites, the password change page is buried several levels deep within account settings, and its location varies across sites.</p>
<p>With Discoverable Destinations, the password manager can use the <code>change-password</code> destination to locate the correct page directly, without the need for site-specific integration or manual maintenance of URL mappings.</p>

<h3 id="technical-requirements">Technical requirements</h3>
<p>Any approach that addresses these user needs must provide the
following.</p>
Expand Down Expand Up @@ -228,27 +244,40 @@ <h3 id="demarcating-destination-content">Demarcating destination content</h3>
</ul>

<h2 id="open-questions">Open Questions</h2>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

A lot, if not all, of this stuff should really just be in the explainer (that's my fault; I moved it across to here). The spec is meant to be definitive, confident, and contemporary.

That's because it needs to be very clear to someone reading it how to implement it.

In our case, this is more of a best practices document, but we still need to be clear and confident.

Whilst we're at the early stages of development, maybe we could soften this, but as we are intending to have a first round of implementations before TPAC, we should probably move some of this back to the explainer.

<div class=issue>
<p>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.</p>
</div>
<h3 id="indicating-the-kind-of-content">Indicating the <em>kind</em> of
content</h3>
<p>The current approach identifies <em>where</em> a destination is located but does not convey <em>what kind</em> 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.</p>
<p>Several possible approaches are under consideration:</p>
<ul>
<li><p>Extending the <code>rel</code> value vocabulary to include more specific destination subtypes (for example, <code>help-human</code> or <code>help-chat</code>). This approach is specific and directly discoverable by User Agents, but risks becoming unwieldy as the number of content kinds grows.</p></li>
<li><p>Using an additional attribute or a companion <code>&lt;meta&gt;</code> element alongside the <code>&lt;link&gt;</code> element to annotate the kind of support offered, keeping the destination identifier stable.</p></li>
<li><p>Deferring this concern to the destination page itself, where structured data markup could describe the available support types. This places the burden on page authors and requires User Agents to fetch and parse the destination page before presenting options to the user.</p></li>
</ul>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Another option: don't address it as part of this spec (we should consider that option).

<div class="issue">
<p>As above, COGA need that we are not yet addressing.</p>
<p>We still need to find reasonable resolution for above problem. We may also delay the resolution till next iteration</p>
</div>

<h3 id="discoverability-and-repetition">Discoverability and
repetition</h3>
<div class="issue">
<p>This is a work-in-progress</p>
</div>
<p>The current approach requires all <code>&lt;link&gt;</code> destination elements to be repeated in the <code>&lt;head&gt;</code> 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.</p>
<p><strong>The Task Force has agreed to adopt the <code>&lt;link&gt;</code> element approach for the first iteration of this specification.</strong> 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.</p>
<p>The following questions remain open for future iterations:</p>
<ul>
<li><p>Should there be a single canonical discovery endpoint, such as a well-known URI, that a User Agent can consult once per origin rather than reading destinations from each individual page? This would reduce per-page overhead but would require an additional HTTP request on first visit to a site.</p></li>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We have been advised against the use of well-known URIs in the strongest possible way, so I don't think we should include mention of that here.

We were also advised against linksets (as they, too, add complexity to the UA) though I am personally sympathetic to their use - I think the point is we'll have to demonstrate that they are really necessary, by having lots of people use the best practice in its current (<link>) form.

Also, if we want to allow the use of linksets in future, we'll have to check that any proposed solution to the 'type of content' problem above will be expressable in a linkset.

<li><p>If a centralized endpoint is provided, how should per-page and per-origin destination declarations be reconciled when they differ? For instance, a sub-site may legitimately need to override destinations declared at the root level.</p></li>
<li><p>What caching expectations should apply to destination declarations, both in the per-page <code>&lt;link&gt;</code> approach and in any centralized discovery document?</p></li>
</ul>
<p>The <a href="https://www.rfc-editor.org/rfc/rfc9264">Linksets</a> format offers one possible path toward centralized discovery and may be revisited in a subsequent iteration.</p>

<h3 id="demarcating-sub-sites">Demarcating sub-sites</h3>
<div class="issue">
<p>This is a work-in-progress</p>
</div>
<p>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.</p>
<p>The <code>&lt;link&gt;</code> element approach handles this naturally. Because every page carries its own <code>&lt;link&gt;</code> 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:</p>
<ul>
<li><p>Semantically</p></li>
<li><p>UI-wise</p></li>
<li><p><strong>Scope is implicit and automatic.</strong> When the user is on a restaurant sub-site page, that page's <code>&lt;link&gt;</code> elements define the applicable destinations. No boundary detection or URL prefix matching is required.</p></li>
<li><p><strong>Overriding destinations is straightforward.</strong> A sub-site page that declares a different <code>contact</code> destination than the root site will naturally present the sub-site's destination to the User Agent, since the User Agent always uses the current page's declarations.</p></li>
<li><p><strong>No additional authoring mechanism is needed.</strong> Content authors control sub-site scoping by controlling which <code>&lt;link&gt;</code> elements appear on each set of pages, typically managed through their CMS templates.</p></li>
</ul>
<p>The Task Force considers sub-site demarcation to be resolved by the per-page <code>&lt;link&gt;</code> approach.</p>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

There are some good suggestions here - thanks!

Though we have not made a decision yet on how to approach sub sites (this text seems to say that we have).

</section>

<section>
Expand Down Expand Up @@ -296,18 +325,18 @@ <h3 id="integration-patterns">Integration Patterns</h3>

<section>
<h2>Requesting Additional Destination Types</h2>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Your additions in this section are great! Very clear; thank you.

<div class="issue">
<p>This section is a placeholder. The process for requesting standardisation of additional destination types is to be defined.</p>
</div>
<p>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:</p>
<p>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.</p>
<p>Parties interested in proposing additional destination types should consider the following criteria:</p>
<ul>
<li><p>The proposed destination type should address a common navigation need that is shared across many websites.</p></li>
<li><p>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.</p></li>
<li><p>The destination type should provide clear accessibility benefits, particularly for users facing cognitive accessibility barriers.</p></li>
<li><p>The destination type should be sufficiently general to apply across different industries and website types.</p></li>
<li><p>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.</p></li>
<li><p>The destination type should not duplicate an existing destination type or overlap significantly with one already in the standard.</p></li>
</ul>
<div class="note">
<p>The formal governance process for proposing, reviewing, and adding new destination types to the standard is under development.</p>
<p>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 <a href="https://github.com/w3c/adapt/issues">WAI-Adapt GitHub repository</a> for discussion by the Task Force.</p>
</div>
<p>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.</p>
</section>

<section>
Expand All @@ -316,20 +345,22 @@ <h2>Privacy and Security Considerations</h2>

<h3 id="privacy-considerations">Privacy Considerations</h3>
<p>Discoverable Destinations use standard HTML <code>&lt;link&gt;</code> 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.</p>
<p>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 <code>&lt;head&gt;</code> and therefore visible to any party that loads the page, no new information is disclosed by processing or presenting it.</p>

<h3 id="security-considerations">Security Considerations</h3>
<p>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 <code>href</code> values in their <code>&lt;link&gt;</code> elements point to legitimate, secure pages.</p>
<p>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 <code>href</code> values in their <code>&lt;link&gt;</code> elements point to legitimate, secure pages under their control.</p>
<p>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.</p>

@matatk matatk May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nice!

We have a security expert on our team here, so I will ask him to review this once we've merged it and are getting closer to 'final' draft.


<h3 id="ai-agent-considerations">Considerations for AI Agent Integration</h3>
<p>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.</p>
<p>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.</p>
</section>

<section class="informative">
<h2>References</h2>

<h3 id="foundational-work">Foundational and Related Work</h3>

<h4 id="ref-link-types">Link Types/Relations</h4>
<h4 id="ref-link-types">Link Types and Relations</h4>
<ul>
<li><a href="https://html.spec.whatwg.org/multipage/links.html#linkTypes">HTML Standard: Link types</a></li>
<li><a href="https://html.spec.whatwg.org/multipage/links.html#other-link-types">Link types managed by the Microformats project</a></li>
Expand All @@ -346,6 +377,14 @@ <h4 id="ref-ai-integration">AI Integration References</h4>
<li><a href="https://github.com/modelcontextprotocol/specification">Model Context Protocol (MCP) Specification</a></li>
<li><a href="https://github.com/webmachinelearning/webmcp">WebMCP</a></li>
</ul>

<h4 id="ref-related-standards">Related Standards</h4>
<ul>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8615">RFC 8615: Well-Known URIs</a></li>
<li><a href="https://www.rfc-editor.org/rfc/rfc9264">RFC 9264: Linksets</a></li>
<li><a href="https://www.w3.org/TR/change-password-url/">A Well-known URL for Changing Passwords</a></li>
<li><a href="https://www.w3.org/WAI/planning/statements/">W3C Web Accessibility Statement Generator</a></li>
</ul>
</section>

<div data-include="../common/acknowledgements.html" data-oninclude="fixIncludes" data-include-replace="true">Acknowledgements placeholder</div>
Expand Down
Loading
Loading