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

Merged
abhina-kumar merged 2 commits into from
Jul 21, 2026
Merged

Refine documentation for DD #337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2526fa
Refine documentation for DD.
abhina-kumar May 2, 2026
ea4359a
Feedback incorporation.
abhina-kumar Jun 29, 2026
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-cognitive-navigation">Navigation Support for Users with Cognitive Disabilities</h4>
<p>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.</p>
<p>With Discoverable Destinations, a User Agent can read standardised destination identifiers from the page's <code>&lt;head&gt;</code> 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.</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-assistive-navigation">Assistive Navigation Technology</h4>
<p>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.</p>
<p>With Discoverable Destinations, assistive navigation technology 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-ai-agent">Agent-based Navigation</h4>
<p>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.</p>
<p>With Discoverable Destinations, the agent can programmatically discover standard page types from the site's <code>&lt;link&gt;</code> elements, enabling consistent and reliable navigation across any compliant site without site-specific configuration.</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.

@abhina-kumar abhina-kumar Jun 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

As discussed on the call, I propose we merge this PR and proceed in two steps:

  1. You can then do a clean-up pass to ensure this specification content aligns with W3C editorial guidelines.
  2. Once that is complete, I will create a follow-up PR to update the explainer , replacing duplicated content with links to the relevant sections of the specification, so that we maintain a single source of truth.

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

@abhina-kumar abhina-kumar Jun 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I think it's important to retain this section either here or in explainer, even if we ultimately decide not to address it within this specification. The reason is the problem is real and well-documented (users with cognitive disabilities genuinely need to know whether they'll reach a human, a chatbot, or an email form), and readers of the specification will naturally ask about it.

By acknowledging the problem and listing the options, we demonstrate that the Task Force has considered it and made a deliberate choice, rather than having overlooked it.

That said, I'm happy to add "not addressing this within the scope of this specification" as a listed option alongside the others, with a note on the trade-off (simplicity and focus for this iteration, at the cost of leaving a known user need unresolved). Would that work?

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

@abhina-kumar abhina-kumar Jun 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

  1. I agree we should not include well-known URIs or Linksets as options in the specification itself, given the strong guidance we have received. However, I think the alternatives we evaluated should be documented somewhere for transparency and to avoid revisiting the same ground in future. The explainer documents would be a natural home for this. Basically, recording what was considered, the rationale for not pursuing each option at this stage, and the conditions under which they might be revisited.

  2. Even without naming specific alternatives, I believe the specification should include a brief note indicating that the Task Force may explore complementary or alternative discovery mechanisms in future iterations, as implementation experience demonstrate the need. This sets appropriate expectations for readers without committing to any particular direction.

  3. Could we take this up on the next call to align on the appropriate level of detail and tone?

@matatk matatk Jul 21, 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.

On this, there isn't a solution yet, but it's acknowledged that there's a gap between well-known URIs and more organic service discovery.

The TAG intends to talk about this at its upcoming face-to-face meeting - here are some pointers to what we'll be discussing: w3ctag/design-reviews#1243

<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>
Comment thread
abhina-kumar marked this conversation as resolved.
</section>

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

<section>
<h2>Requesting Additional Destination Types</h2>
Comment thread
abhina-kumar marked this conversation as resolved.
<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>
Comment thread
abhina-kumar marked this conversation as resolved.

<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