From 5d980783e31ee3e2ea69167a42c0f1d06c0968d5 Mon Sep 17 00:00:00 2001 From: Matthew Tylee Atkinson Date: Tue, 22 Oct 2024 14:29:10 +0100 Subject: [PATCH] Add explainers for proposed new specs (#261) Merging this so we can point to the TPAC 2024 version of things. --- explainers/README.md | 604 ++++++++++++++++++++++++++ explainers/accessibility-meta.md | 66 +++ explainers/accessibility-reporting.md | 97 +++++ explainers/symbols.md | 286 ++++++++++++ explainers/well-known-destinations.md | 452 +++++++++++++++++++ 5 files changed, 1505 insertions(+) create mode 100644 explainers/README.md create mode 100644 explainers/accessibility-meta.md create mode 100644 explainers/accessibility-reporting.md create mode 100644 explainers/symbols.md create mode 100644 explainers/well-known-destinations.md diff --git a/explainers/README.md b/explainers/README.md new file mode 100644 index 0000000..cd1fbe0 --- /dev/null +++ b/explainers/README.md @@ -0,0 +1,604 @@ +# WAI-Adapt Explainer + +## Authors + +* W3C WAI-Adapt TF participants + +## Participate + +* Issues: https://github.com/w3c/adapt/issues +* Discussions: https://github.com/w3c/adapt/discussions + +## Overview + +**Note:** This is the Explainer for the Adapt TF's work as a whole—you can find more details on specific projects in the other files in this directory. + +**FIXME:** The "explainer" below contains useful info, but is not in the correct format (concentrating on end-user use cases first; using standard headings); it needs to be re-written to fit that format—and perhaps have the content-module-specific parts factored out into a content module explainer? Also, the list of modules below should refer to the other explainers that exist in this directory. + +**FIXME:** The Explainer template doesn't have an "Overview" section (though maybe that's OK in this case). + +## Introduction + +People have very different needs. There are many people with cognitive +and learning disabilities that affect their ability to interact with the +web. Some people cannot process numeric information (dyscalculia), but +others understand numbers better than words. Some people with severe +language disabilities use symbols to represent words; some people need +(or want) simplified user-interfaces. Different people find different +layouts and types of content easier to understand, and what is useable +and understandable by one person can be be too complex for another. The +WAI-Adapt Task Force seeks to address these varied and conflicting user +needs, so that content can be made more understandable to individual +users based on their unique requirements. The various WAI-Adapt +specification modules described in this Explainer provide various means +for web technologies to address these requirements. + +The various WAI-Adapt module specifications enable authors to +selectively add semantic information about content to enable content and +interface personalization for individual users. In turn this facilitates +user-agents for people with learning and cognitive disabilities. + +WAI-Adapt technologies allow authors to add additional semantic +information using a collection of new attributes and values, with (in +most cases) a fixed token list (taxonomies). This document provides an +explanation for understanding how the WAI-Adapt attributes can be used +to personalize a more accessible web site. + +### Further details + +> **FIXME:** This was the "Introduction" section, with the above being the "Abstract"—but Explainers are intended to start with a brief overview. This Explainer is an umbrella one, so maybe a bit different, but this still need some work to bring it in line with reader expectations. + +> **FIXME:** Perhaps this material could be put in an appendix? + +The WAI-Adapt specification modules: + +- Expands upon the types of accessibility information that the author + can provide; +- Facilitate preference-driven individual personalization; +- Enable the author to specify key semantics to support users with + cognitive impairments; +- Define a syntax for adaptable content such as: links, buttons, + symbols, help, and keyboard shortcuts. + +Personalization involves tailoring aspects of the user experience to +meet the preferences or needs of individual users. For example, having +familiar terms and symbols is critical for effective use of web content +for many as described in the user scenarios and use cases published in +the [Making Content Usable (for COGA +people)](https://www.w3.org/TR/coga-usable/). However what is familiar +to one user will inevitably be new and foreign to another. +Personalization based on WAI-Adapt AAC symbol support technologies +supports loading a set of symbols that is appropriate for the specific +user, ensuring that each user is presented with familiar symbols. + +Technology holds the promise of being extremely flexible and the design +of many systems includes the expectation that users can optimize their +interaction experience according to their personal preferences or +accessibility needs. + +### Why We Need WAI-Adapt + +> **FIXME:** Perhaps this material could be put in an appendix? + +WAI-Adapt will allow assitive technology to: + +1. adapt to and meet the user's needs. Users who have difficulty with + established, mainstream patterns can interact with interfaces + modified to their preferences and abilities. +2. modify levels of complexity as people's skills improve or decline + over time. For example, extra support may be critical for some + people but distracting for others. +3. provide better support to users who require: + - familiar and consistent symbols, iconography, and graphics + - tooltips or similar on-demand help or clues + - language they understand + - fewer or more constrained features + - clearer distinction between native and third-party content + - custom keyboard shortcuts + +To achieve this, we need standardized terms and supportive syntax. These +can be linked to associated symbols, terms, translations and +explanations. This allows modifications based on an individual's +personal preferences. + +
+ +Example of sending an email: + +An author programmatically identifies that a button sends an email. +Based on user preference settings the interface can be modified to: + +- render the button with an alternative term, and/or furnish an + additional tooltip that is understandable by the individual user; +- include F1 help that explains the send function in simple terms; +- associate the button with a keyboard shortcut that is always used for + send (Submit); +- identify the button as important and always rendered in an emphasized + form. + +
+ +### Use Case Examples + +> **FIXME:** +> +> * Perhaps this material could be put in the "User research" section? +> +> * The linked "Requirements" doc is out-of-date. +> +> * These examples are _way_ too detailed, and refer to attributes that don't exist yet—need to re-phrase to talk _briefly_ about the _problems_ being solved, but not the specific mechanism. It is OK to say (in a later section) that the general solution is to provide attributes to provide additional element-level semantics, but most of these are not fleshed out and ready for implementation yet, so they shouldn't be mentioned in specific detail (and when they are, they should be in separate explainers). + +[Requirements for WAI-Adapt](requirements/) elaborates many use cases +that further contextualize the above summary of user needs. These +example use cases form the basis of requirements for this technology. +WAI-Adapt enables developers to create targeted extensions as additional +use cases are encountered. + +Examples + +- [Easily Distracted / Overwhelmed](#distracted) +- [Difficulty Understanding Numbers](#difficulty_numbers) +- [Mild-Moderate Language Impairment / Learning + Disability](#learning_disability) +- [Severe Language Impairment](#language_impairment) +- [Working Memory and Short-term Memory Impairment](#memory_impairment) + +#### Easily Distracted / Overwhelmed + +Someone who is either easily distracted or can be easily overwhelmed +with too much information on a web page needs the ability to simplify +the page. They want just the critical information, and need anything +that is not integral to the understanding and use of the page +suppressed. + +
+ +Example: The user wants to get the latest weather report for their city +and goes to a weather website. + +Finding the actual weather forecast is actually a little challenging +even if you have no disabilities due to all the additional content on +the screen; along with advertisements, there is also the day's top +stories, trending news, and social media to cognitively filter. If you +are easily overwhelmed or distracted getting the key information about +today's weather is a challenge. Having the ability to personalize and +prioritize all but the key information (i.e. just the weather forecast +for my city) is critical for this user. + +
+ +In this example, the author can mark the `
`, `

`, or `

` +that contains the actual weather report and any associated tools to +manipulate the weather report (i.e. city search, hourly vs. 5 day +forecast, etc.) with the `adapt-simplification` attribute (with a value +of "critical"), and mark the other on-screen content as "medium" +(default) or "low". (e.g. +`

`*Today’s forecast is a high +of 95° and a low of 40°*`

`) + +For websites which rely on advertising revenue, it may be undesirable to +completely suppress advertisements. We envision that this attribute +could also facilitate relocating the most critical sections of a website +above anything that is a lower priority. (i.e. Content re-ordering) + +WAI-Adapt recognizes that appropriate simplification will often be task +determined. A complex page will often support multiple tasks each of +which could be critical to the user requiring simplification at +different times. We propose to investigate how we might facilitate users +defining what task is critical to them in the moment rather than +pre-determining what is primary or secondary in advance. + +#### Difficulty Understanding Numbers + +Someone who has dyscalculia will have difficulty understanding numbers +and will have a hard time interacting with websites that use numbers to +convey information. Therefore, critical numeric information must be +provided in an alternative format that the user can understand. + +
+ +Example: The user wants to get the latest weather report for their city +and goes to a weather website. + +For today’s forecast, it shows a high of 95° and a low of +40°. This representation is not understandable for particular user. +Presenting this numeric information as a symbol or text would benefit +the user. For example, next to the number 95, there could be: + +- a picture of someone wearing shorts and a tee-shirt with the sun above + or +- simply a text alternative of “Very warm”. + +Next to the number 40, there can be: + +- a picture of someone wearing a jacket with pants, or +- a text alternative of “Very cold”. + +Next to the humidity index of 90%, there could be a text alternative of +“muggy”. + +
+ +In this example, the author would mark up the numbers using the +`adapt-numberfree` attribute. The default would show the numeric value. +Those needing an alternative representation for numbers, would get an +associated image or description/values as simplified text instead. + +It is important to note that people with dyscalculia are often very good +with words, so long text can be better than short numbers. + +#### Mild-Moderate Language Impairment / Learning Disability + +Those who have a moderate Language Impairment / Learning Disability may +have a limited vocabulary. They will only know terms that are in the +core vocabulary they have learned. They may also use symbols to +represent words and concepts. + +
+ +Example: The user may know the word "name" or "last name" but not +recognize the term "family name" or "surname" as cognates. + +For some users, learning new terms is a very slow process, requiring +hours of work. For these users, reading web content may also be a very +slow process, so that finding the information desired on some particular +web page can present a laborious barrier. The ability to personalize a +web page and present symbols instead, or alongside content can help some +users better and more promptly understand the content being provided + +
+ +Note that some people with language disabilities are good at numbers. +They will want a long string of text replaced with a short number: +` normally this is the expected outcome`. +This is the opposite of the numberfree example. + +Additionally, because reading content for some users is extremely +time-consuming, they may also want less content and fewer features on a +given web page. + +#### Severe Language Impairment + +Some users with a severe speech and/or physical impairment may +communicate using symbols, rather than written text, as part of an +Augmentative and Alternative Communication (AAC) system. The use of +symbols to represent words is their primary means of communication when +both consuming and producing information. Symbol users face a wide +variety of barriers to accessing web content, but one of the main +challenges is a lack of standard inter-operability between different +proprietary symbol sets, or a mechanism for translating the same concept +from one symbol set to another. + +User Stories include: + +- An assisted living home authors adult education courses and + life-skills content, for example, how to make dinner using a + microwave. Within their core user-base, users are accustomed to + different symbol sets. The authors want to create content for all + users across various symbol sets. +- A large banking site wants people to be as autonomous as possible + while using their services. They provide augmented symbol references + onto their core services. They need a mechanism to programmatically + support multiple symbol sets within the code. +- People who know different symbol sets wish to talk to each other. +- A government agency creating information sheets about human rights and + patient rights are seeking feedback from impacted users. They add + symbols from a common symbol set to support a majority of different + users. The agency would prefer to use a common symbol reference to + support people who use or require different symbols. This allows all + symbol set users to both read and edit the content. + +
+ +Example: Using the `adapt-symbol` attribute, an author programmatically +tags the label for a form input with the appropriate symbol value. Based +on user preference settings, a browser helper application or stand-alone +tool could then render that label using an appropriate symbol, +alternative term, and/or furnishes an additional tool-tip that is +understandable by the individual user. Using the [Bliss +Symbolics](https://www.blissymbolics.org/) set's unique reference +numbers as our 'taxonomy', other symbol sets can map their equivalent +symbols against the Bliss set. + +` ` +` ` + +Where the symbol value 14855 maps back to "Home". + +
+ +##### Proof of Concept: Symbol Example + +In the screen shots below, a browser extension uses the `adapt-symbol` +attribute to load symbols that are familiar to the user. + +Note that users learn a specific symbol vocabulary. However, the various +symbol vocabularies are mutually unintelligible: users familiar with one +set of symbols may not be familiar with or understand an alternative +set. WAI-Adapt's `adapt-symbol` attribute offers a mechanism to +translate between symbol sets, to allow people to communicate with one +another where it was previously not possible. + +
+screen shot, no symbols +
The original page
+
+ +
+ +
The same page loaded, but the user-agent has removed content +and added symbols
+
+ +
+ +
The same page loaded, but the user-agent has removed content +and added different symbols that this user is more familiar +with
+
+ +#### Working Memory and Short-term Memory Impairment + +Users may have differences in both working and short-term memory. For +some users the number of items that can be held in working memory is a +fraction of the amount most users can hold in memory. Whereas most +adults can repeat about seven digits in correct order, some users may +only manage two or three digits. When these users become distracted, +they are also likely to forget any information in their working memory. + +
+ +Example: Many processes consist of a sequence of separate steps or +actions which must be performed by a user to complete a process or +workflow. + +Users need to remember completed tasks in order to identify their +location in a process. In addition, a user must be able to navigate to +completed tasks to make modifications or corrections. + +
+ +A step indicator allows an author to define steps within a process or +represent an entire user path outside of the context of a defined +process. This includes turning steps between defined processes into +breadcrumbs or linked steps that identify completed tasks. This allows +the user to navigate back to completed steps and identify a user's +current location in a path. + +More information on personas and user needs can be found in +Making +Content Usable for People with Cognitive and Learning Disabilities. + +### Out of Scope + +While the intention of this work is to introduce a new set of attributes +to support WAI-Adapt, the following work items are out of scope: + +- Develop an API for browsers or other user-agents +- Develop or produce supporting technology (browser extension, + stand-alone software, etc.) +- Develop or produce an authoring tool to support the new attributes +- Produce a symbol set for `adapt-symbol` + +We encourage a the development of these items and a list of +implementations can be found on [our +wiki](https://github.com/w3c/adapt/wiki). + +### Modules + +WAI-Adapt specifications will be published as individual modules. How +many modules will eventually be created is unclear at the time of this +writing. However, each module specification will include use cases and +vocabularies. At this time only one specification module is advancing +toward Candidate Recommendation status at W3C: + +- [WAI-Adapt: Symbols Module:](symbols/index.html) + + This module provides vocabularies that enable user-agents to augment + or adapt content to allow authors to support AAC symbols. + +Additional modules, some available in early drafts, may include: + +- Use-cases and vocabularies for identifying the purpose of controls, + symbols and user interface elements, and supports simplification and + avoiding distractions. + +- [WAI-Adapt: Help and Support Module:](help/index.html) + + The first working draft of this module is now available. + + This module addresses adding information about the content to enable + help scaffolding and additional support for different user scenarios. + +- [WAI-Adapt: Tools Module:](tools/index.html) + + The first working draft of this module is now available. + + This module addresses adding information about the content to enable + user-agents and extensions to provide additional support to the user. + One example is adaptable breadcrumbs. + +## Vocabulary Structure + +WAI-Adapt is made of a vocabulary of properties and their values. This +generic structure makes it possible to apply WAI-Adapt in a variety of +contexts by adapting how the vocabulary is instantiated. The [Vocabulary +Implementations](#vocabulary-implementations) section below describes +current ways to use the vocabulary. + +### Properties + +Properties are the main units of WAI-Adapt types supported by the +vocabulary. A given property supports a specific type of WAI-Adapt. That +property would only be used once on a given piece of content, but +multiple different properties could be used on the same piece of content +to address different needs. + +### Values + +Values provide the specific WAI-Adapt information for the property. The +possible values for each property are elaborated in the definition of +the property in the modules. Some properties require the value to come +from a predefined list of possible values, others can accept arbitrary +strings, and some may accept multiple values. The attribute value may be +one of the following types: + +ID reference +Reference to the ID of another element in the same document + +ID reference list +A list of one or more ID references. + +integer +A numerical value without a fractional component. + +number +Any real numerical value. + +string +Unconstrained value type. + +token +One of a limited set of allowed values. + +token list +A list of one or more tokens. + +URI +A Uniform Resource Identifier as defined by [RFC +3986](http://www.ietf.org/rfc/rfc3986.txt) \[\[RFC3986\]\]. It may +reference a separate document, or a content fragment identifier in a +separate document, or a content fragment identifier within the same +document. + +
+ +The attributes and values in this specification are not intended to +overide the semantics exposed in the Accessibility Tree, but rather +augment them. In the case of conflict between an element's semantics and +the attribute values, validation algorithms should issue a warning but +not an error. + +
+ +## Vocabulary Implementations + +### Current Usage + +This publication of the WAI-Adapt provides several *key-value pairs* +(attribute = value). These attributes include but are not limited to: + +- [adapt-action](symbols/#action-explanation) +- [adapt-destination](symbols/#destination-explanation) +- [adapt-purpose](symbols/#purpose-explanation) +- [adapt-symbol](symbols/#symbol-explanation) + +Other properties exist or will be developed as the modules mature. + +### Technology Comparison Summary + +The task force reviewed various vocabulary options before deciding upon +the use of the HTML attribute syntax. The list of technologies included: + +- [RDFa Lite](https://www.w3.org/TR/rdfa-lite/) +- [HTML Microdata](https://www.w3.org/TR/microdata/) +- Additional ARIA attributes (e.g. `aria-action`) +- AUI-prefixed attributes: a new, WAI-Adapt specific set of attributes + (e.g. `aui-action`) +- A new single attribute, purpose, to encode both properties and values +- A new single attribute with properties and values encoded using inline + css syntax of key/value pairs +- An extension of the above single attribute using CSS key/value pairs + and simple text content +- Three new attributes for token, value, and URI, respectively +- Value pairs - a WAI-Adapt type attribute and an associated value + attribute. +- Negotiate new WAI-Adapt attributes into native host languages +- Embed WAI-Adapt data via JavaScript Object Notation (JSON) +- Use of the existing data- attribute mechanism of HTML + +#### Considerations in the decision process: + +Authoring +ease of authoring and potential ambiguity between WAI-Adapt and existing +features; + +User-Agents +ease of determining and parsing the properties & values and the ability +to implement as an extension; + +Host Languages +requirement for special host language support, works in multiple +languages, integrates with ARIA and HTML, easy extension of the +vocabulary, and needed number of new features; + +Functionality +necessity of multiple properties and interaction between properties, +integration with other vocabularies, likely search engine support for +content alternatives, and typed value support; + +Strategy +avoid segregation of accessibility from other features, provide a clear +path to join with other W3C WAI-Adapt efforts, and stable enough to +avoid modification of authored content over time; + +The details of our research and discussion are documented on the +[Comparison of ways to use vocabulary in +content](https://github.com/w3c/adapt/wiki/Comparison-of-ways-to-use-vocabulary-in-content) +and [Prototypes with data +dash](https://github.com/w3c/adapt/wiki/Prototypes-with-data-dash-*-(Take-2)) +pages in our Wiki. + +### Stakeholders + +This document is useful for: + +- Content creators who want to accommodate as many users as possible, + including AAC users, and people with learning & cognitive + disabilities. +- Content creators who want to create adaptable content that meets the + users' preferred experience +- Technology developers and providers who want to build technologies + that enable more people to use the web effectively +- Developers of symbol languages and related technologies +- Students who wish to develop a new software project that meets a real + need +- Policy makers who want to understand what is possible for inclusion + +For early implementations of content we suggest including a link to an +[extension +implementation](https://github.com/w3c/adapt/wiki/Implementations-of-Semantics) +that can maximize the benefit for users. + +### Acknowledgements + +> **FIXME:** placeholder + +### Appendix: All proposed attributes and modules + +> **FIXME:** This is just here to keep a more visible record of what _was_ proposed—need to find a more useful place, e.g. the wiki. + +#### Attributes + +* `adapt-action` +* `adapt-destination` +* `adapt-purpose` (autocomplete reasons++) +* `adapt-symbol` +* `adapt-simplification` (critical, ...) +* `adapt-numberfree` +* `adapt-easylang` + +#### Modules + +* Content (still wanting to propose the attributes from there, but concentrating on symbols only for now) +* Symbols +* Help and support +* Tools diff --git a/explainers/accessibility-meta.md b/explainers/accessibility-meta.md new file mode 100644 index 0000000..3f7a046 --- /dev/null +++ b/explainers/accessibility-meta.md @@ -0,0 +1,66 @@ +# Accessibility statement schema and metadata + +## Authors + +- Matthew Tylee Atkinson (@matatk), Samsung Electronics + +## Introduction + +Accessibility statements provide detailed information from a site developer about: + +* Which assistive technologies they support. +* Known issues. +* Plans for further accessibility improvements. +* Contact details so that visitors can request help, or report problems. + +This spec provides a standard schema for providing this information, with the following goals. + +## Motivating Use Cases + +* Improved consistency of accessibility statements across sites. + - This will make the statements more useful for humans. +* Make the statements machine readable. + +> **TODO:** Prediction: machine readability may give some organisations concerns (as it makes researching easier). + +## Non-goals + +* Specifying the _location_ (URI) of the accessibility statement. This is the subject of a separate specification. +* Providing the means for accessibility reporting, in the following ways. Both of these are covered by a separate specification. + - Providing the means for accessibility test results to be automatically, semi-automatically, or manually reported. + - Providing the means for people to report difficulties they are having on a given page. + +> **TODO:** Link to the other specs/explainers. + +## User research + +> **TODO** + +## Schema for accessibility statements + +> **TODO** + +This section will detail: + +* What types of information can go into an accessibility statement. +* How each is to be identified and encoded. + +## Key scenarios + +> **TODO** + +## Detailed design discussion + +> **TODO** + +## Considered alternatives + +> **TODO** + +## Stakeholder Feedback / Opposition + +> **TODO** + +## References & acknowledgements + +> **TODO** \ No newline at end of file diff --git a/explainers/accessibility-reporting.md b/explainers/accessibility-reporting.md new file mode 100644 index 0000000..19ccf20 --- /dev/null +++ b/explainers/accessibility-reporting.md @@ -0,0 +1,97 @@ +# Accessibility reporting: use cases, endpoints, and schema + +## Authors + +- Matthew Tylee Atkinson (@matatk), Samsung Electronics + +## Introduction + +> **TODO** + +This work builds on the [Reporting API](https://www.w3.org/TR/reporting-1/). + +## Motivating Use Cases + +* Providing the means for accessibility test results to be automatically, semi-automatically, or manually reported. +* Providing the means for people to report difficulties they are having on a given page. + +> **Note:** It is anticipated that using infrastructure such as the Reporting API will be particularly helpful in situations where pages are comprised of content obtained from multiple sources, because the reporting can be done "at the edge" where this content is combined. +> +> To be useful, though, this will require organisations to be able to reproduce (or at least approximate) the assembled content, based on the information provided by the report. + +## Non-goals + +* Specifying the location (URI) of the accessibility statement. This is the subject of a separate specification. +* Specifying the schema of the machine-readable accessibility statement. This is the subject of a separate specification. + +> **TODO:** Link to the other specs/explainers. + +## User research + +> **TODO** + +## Accessibility reporting mechanisms + +### Reporting endpoint for accessibility results + +> **TODO** + +We will standardise an endpiont to be used for accessibility reporting—or possibly two endpoints: + +* A reporting endpoint for (automatic, semi-automatic) inspection tooling. +* A reporting endpoint for issues that a user reports (manually, or with assistance from a tool that may include attachments, like screengrabs) when they encounter an error. + +### Schema for automated accessibility reports + +> **TODO** + +We will standardise a schema to be used by automated accessibilty tooling. + +Challenges include: + +* Scoping (Just WCAG, or also best practices—in which case, how should they be flagged?) +* Identifying the part of the page that is affected. +* Attachments. +* Units. + +We will probably find help with this via the [Accessibility Conformance Testing (ACT)](https://www.w3.org/WAI/standards-guidelines/act/). + +### Schema for accessibility barriers affecting users + +> **TODO** + +We will standardise a schema for providing reports from users. + +## Key scenarios + +### An automated accessibility scanner + +> **TODO** + +### Manual in-browser accessibility inspection tools + +> **TODO** + +### A site visitor experiencing barriers + +> **TODO** + +## Detailed design discussion + +> **TODO** + +## Considered alternatives + +> **TODO** + +## Stakeholder Feedback / Opposition + +> **TODO** + +## References & acknowledgements + +> **TODO** + +* [Research Questions TF: Use cases for the Reporting API](https://www.w3.org/WAI/APA/task-forces/research-questions/wiki/Reporting_API_Use_Cases) +* [Accessibility Conformance Testing (ACT)](https://www.w3.org/WAI/standards-guidelines/act/) +* [Reporting API](https://www.w3.org/TR/reporting-1/) \ No newline at end of file diff --git a/explainers/symbols.md b/explainers/symbols.md new file mode 100644 index 0000000..e12754e --- /dev/null +++ b/explainers/symbols.md @@ -0,0 +1,286 @@ +# WAI-Adapt: Symbols Module Explainer + +## Authors + +- Matthew Tylee Atkinson (@matatk), Samsung Electronics + +## Participate + +* Issues: https://github.com/w3c/adapt/issues +* Discussions: https://github.com/w3c/adapt/discussions + +## Contents + + + +- [Introduction](#introduction) + * [Demo](#demo) +- [Goals](#goals) +- [Out of scope](#out-of-scope) +- [Important notes on symbols and rendering](#important-notes-on-symbols-and-rendering) +- [User research](#user-research) +- [The `adapt-symbol` attribute](#the-adapt-symbol-attribute) + * [Mapping concepts to symbols (in general)](#mapping-concepts-to-symbols-in-general) + * [Concept IDs: keying schemes](#concept-ids-keying-schemes) + + [BCI concept IDs as attribute values](#bci-concept-ids-as-attribute-values) + - [Advantages](#advantages) + - [Disadvantages](#disadvantages) + + [Bliss characters' Unicode representations as attribute values](#bliss-characters-unicode-representations-as-attribute-values) + - [Advantages](#advantages-1) + - [Disadvantages](#disadvantages-1) + - [Unknown factors](#unknown-factors) + * [Multiple concepts per attribute value](#multiple-concepts-per-attribute-value) + * [Looking up concepts](#looking-up-concepts) +- [The W3C AAC Symbol Registry](#the-w3c-aac-symbol-registry) +- [Privacy considerations](#privacy-considerations) +- [Considered alternatives](#considered-alternatives) +- [Stakeholder feedback/opposition](#stakeholder-feedbackopposition) +- [References](#references) +- [Acknowledgments](#acknowledgments) + + + +## Introduction + + + +Some people find graphical symbols easier to interpret than written text. +They may find that when symbols are presented alongside text content, that content is easier to understand. +But there are many different symbol sets in use, and people don't tend to learn more than one. + +We propose the `adapt-symbol` attribute, which allows content authors to mark up the _concepts_ relevant to their content, +so that the appropriate symbol(s) for that concept can be rendered for the user, +using _their chosen symbol set_. + +We use the set of concepts maintained by [Blissymbolics Communication International](https://www.blissymbolics.org/) (BCI). +These concepts underpin the Blissymbolics (or "Bliss") language—though our use of the concepts is strictly for mapping from a concept to the appropriate aymbol(s) for the user, and is not grammatical in nature. + +We're working closely with BCI on this specification, and the W3C AAC Symbol Registry (more details below). + +### Demo + +A proof-of-concept authoring tool demo can be found at: http://matatk.agrip.org.uk/adaptable-content-authoring-tool/editor/ + +Please note the following limitations: + +* It only supports Bliss symbols. + +* The given example does not represent the typical use case of sparse use of symbols, mainly to annotate content such as media chapters. + +## Goals + +* Allow content authors to add element-level metadata that link parts of the content to well-known concepts. This, in turn, supports the user need of having content annotated with symbols that the user can understand. + +## Out of scope + +* Mapping from the concepts to the appropriate symbols for the user, and rendering those symbols (this is left to the UA, or an extension). + +* Providing translation—the concepts are specified by the author to match the language of the page's content; if the page content were to be translated, the concepts would need to be translated too. + +* Providing an exhaustive list of concepts (the [W3C AAC Symbol Registry](#the-w3c-aac-symbol-registry), described below, aims to do this). + +## Important notes on symbols and rendering + +Though rendering is out of scope, it's important to be aware of the nature of symbols, and different symbol sets: + +* Symbols are graphical objects (i.e. vector or bitmap images). + +* A concept (e.g. "tea") may map to zero or more symbols in any given symbol set (zero is a possibility because the symbol set may not _have_ a symbol for a particular concept). + +* A concept will not necessarily map to the same number of symbols across symbol sets. + +## User research + +> [!NOTE] +> This work has been developed over several years, with input from the Cognitive Accessibility TF, and experts from BCI. We will add references to some key elements of that background work here. + +## The `adapt-symbol` attribute + +The intent of the `adapt-symbol` attribute is to link a _concept_ (for which the UA will render an appropriate symbol for the user) to some content (usually text) on the page. + +The value of the `adapt-symbol` attribute is a representation of a concept, which will be rendered as one or more symbols by the UA. There are several ways that the concepts may be encoded, which is the subject of current discussion. + +### Mapping concepts to symbols (in general) + +There are a number of ways we may identify, or "key", concepts—some alternatives are discussed below. + +Regardless, the overall appraoch for using the attribute would be the same: + +1. The goal of the `adapt-symbol` attribute is to match some content (e.g. a word, or a video chapter title) to the appropriate symbol(s) for the user. + +2. This is done by having the author specifcy the _concept_ that the content relates to. + +3. The concept may map, in any given symbol set, to one or more symbols (or zero symbols, if the set has no symbol for that concept). + +4. The rendering of symbols would be down to the UA—we have made a demo, and are working on a visual layout test suite. + +Therefore, setting aside the means of identifying concepts, the basic markup would be as follows. + +```html +

Would you care for some tea?

+``` + +The following sections compare ways to identify concepts. For now, let's assume they will be integers. + +Here are three examples of how the `adapt-symbol` attribute could be used. + +1. Symbols for individual words. + + ```html + Cup of Tea + ``` + +2. Symbols used with an image (`alt` text represented as a symbol). + + ```html + Cup + ``` + +3. Symbols with conjugation. In this example a symbol is used for "her + name" for the conjugated Hebrew word, שמה. The comma is used to join the conjugated values, "her" (14707) and "name" + (15691). If the gender is not important, you can just use the value + for name (15691). + + ```html + שמה + ``` + +### Concept IDs: keying schemes + +There is [ongoing discussion on how the concepts should be expressed in the HTML markup in issue 240](https://github.com/w3c/adapt/issues/240). This section makes three suggestions. + +#### BCI concept IDs as attribute values + +***This keying scheme maps one integer (the BCI concept ID) to a concept.*** + +BCI maintains a dictionry of concepts, with corresponding Bliss symbols, and written-language definitions. + +##### Advantages + +* Simple—provides a 1:1 mapping between concept and key that identifies the concept. + +* Does not expose implementation details of Bliss symbols to content authors. + +* Relatively minimal lag time between a concept addition/update and availability via authoring tools, or the W3C AAC Symbol Registry. + +##### Disadvantages + +* Allows us to only specify concepts available in the Bliss language. (But we can still map to any symbol set, based on those concepts.) + +#### Bliss characters' Unicode representations as attribute values + +***This maps one or more representations of Bliss characters (symbols) to a concept.*** + +Instead of BCI concept IDs (integers), we could use: + +* Unicode code points for Bliss symbols (directly), or + +* Hex (or other) representations of Unicode code points that correspond to Bliss symbols. + +> [!IMPORTANT] +> Basing the key into the concept dictionary on Bliss characters means that: +> +> * Regardless of the symbol set being used for output, the concept is expressed in terms of Bliss symbols. +> +> * The values used relate to the Unicode code points for these Bliss characters. Because there are approximately 6,500 Bliss concepts, but only around 1,400 Bliss characters being added to Unicode, this means that some concept identifiers will need to contain multiple Bliss character representations. + +> [!NOTE] +> Further details can be found in our comment on issue 240 (this comment only suggest the user of code points directly, though): . + +##### Advantages + +* Based on an existing standard (Unicode). + +##### Disadvantages + +* Exposes the implementation details of Bliss to someone writing this markup. + + - As part of this, it's more complex than using atomic keys (such as BCI concept IDs): some concepts that would be represented by one BCI ID would need more than one Bliss character representation to identify them. + + +##### Unknown factors + +* Unclear as to what the process for adding additional Bliss characters to Unicode would be. + +* The time between new concepts being added to Bliss, and them being available via Unicode would likely be significant, due to the release cadence of Unicode. + +### Multiple concepts per attribute value + +Though it is not expected to be used extensively, we have considered how multiple concepts may be referenced within one attribute value. + +As separate Bliss characters (or their representations) are space-separated, it is proposed that if multiple concepts were to be included in a single `adapt-symbol` attribute value, they would be comma-separated. For example: + +```html + [!NOTE] +> We want to maintain consitency with how other parts of the platform handle this—we're very-much open to using other delimiters if needed. + +### Looking up concepts + +The content author needs to be able to find known concepts, and their associated identifier. This is addressed in the next section. + +## The W3C AAC Symbol Registry + +> [!NOTE] +> We are planning to split this explainer off into a separate file, to avoid explainers that are too long. + +The registry brings BCI's dictionary of concepts into W3C space. Each record in the registry contains: + +* A uniquely-identifying key. + +* A description of the concept in a written language (e.g. English). + +* The Bliss symbol(s) that embody this concept in the Bliss language. + +The registry can be found at: https://www.w3.org/TR/aac-registry/ + +> [!NOTE] +> The registry's key for identifying concepts is presently the concepts' BCI concept ID (an integer). However, as discussed above, we are in discussions with potential implementers on whether the corresponding Bliss Unicode code point(s) for a given concept could be used instead. + +## Privacy considerations + +> [!NOTE] +> This section is to be expanded. + +Because the rendering of symbols is expected to be done by injecting them into the HTML, the site could determine that the user is using symbols, and which symbol set is in use. + +## Considered alternatives + +> [!NOTE] +> This section is to be added. + +## Stakeholder feedback/opposition + +Our work is currently focused on working with BCI within W3C to solidify our recommendations for the syntax of the `adapt-symbol` attribute. We have run several breakouts on the work, and will more actively seek feedback once this is decided. + +Through prior TPAC meetings, and [issue 240](), we have been discussing authoring consdierations with WHATWG. + +We plan to seek input from implementers following the resolution of the concept keying issue. + +We have engaged with experts in the COGA TF regarding the appropriateness of building upon the concepts identified by BCI—this work actually began within the COGA TF, with the input of renowned experts on AAC and symbols. Bliss is used because it is comprehensive, and has a mature process for the addition and updating of concepts. + +## References + +> [!NOTE] +> This section to be added. + +## Acknowledgments + +* Lisa Seeman, COGA TF + +* Russell Galvin, BCI + +* WAI-Adapt TF participants diff --git a/explainers/well-known-destinations.md b/explainers/well-known-destinations.md new file mode 100644 index 0000000..f6b479e --- /dev/null +++ b/explainers/well-known-destinations.md @@ -0,0 +1,452 @@ +# WAI-Adapt: Well-known destinations Explainer + +## Authors + +- Matthew Tylee Atkinson (@matatk), Samsung Electronics + +## Participate + +* Issues: https://github.com/w3c/adapt/issues +* Discussions: https://github.com/w3c/adapt/discussions + +## Contents + + + +- [Introduction](#introduction) +- [Motivating Use Cases](#motivating-use-cases) +- [Out of scope](#out-of-scope) +- [User research](#user-research) +- [Well-known destinations: technical requirements](#well-known-destinations-technical-requirements) +- [Option 1: Well-known URIs, and HTML link types](#option-1-well-known-uris-and-html-link-types) + * [The well-known destination namespace](#the-well-known-destination-namespace) + * [Defining a site](#defining-a-site) + * [Enumerating well-known destinations](#enumerating-well-known-destinations) + * [Visiting a well-known destination directly](#visiting-a-well-known-destination-directly) + * [Updating a well-known destination](#updating-a-well-known-destination) + * [Expressing when a link points to part of a well-known destination](#expressing-when-a-link-points-to-part-of-a-well-known-destination) + * [Demarcating destination content](#demarcating-destination-content) +- [Option 2: Linksets, and HTML link types, and one Well-known URI](#option-2-linksets-and-html-link-types-and-one-well-known-uri) + * [The well-known destination namespace](#the-well-known-destination-namespace-1) + * [Defining a site](#defining-a-site-1) + * [Enumerating well-known destinations](#enumerating-well-known-destinations-1) + * [Visiting a well-known destination directly](#visiting-a-well-known-destination-directly-1) + * [Updating a well-known destination](#updating-a-well-known-destination-1) + * [Expressing when a link points to part of a well-known destination](#expressing-when-a-link-points-to-part-of-a-well-known-destination-1) + * [Demarcating destination content](#demarcating-destination-content-1) +- [Security \& Privacy considerations](#security--privacy-considerations) +- [Considered alternatives](#considered-alternatives) + * [Sitemaps](#sitemaps) + * [Using `rel` attribute values alone](#using-rel-attribute-values-alone) +- [Stakeholder feedback/opposition](#stakeholder-feedbackopposition) +- [References \& acknowledgements](#references--acknowledgements) + * [Foundational work](#foundational-work) + + [Destinations](#destinations) + + [Well-known URLs](#well-known-urls) + + [Linksets](#linksets) + + [Link types/relations](#link-typesrelations) + + + +## Introduction + + + +Web sites can contain a huge array of varied and engaging content. This content, and the means of navigating around it, can be presented in almost any way, which makes for tailored and compelling experiences. However, whilst there are several conventions when it comes to navigation, this variability can pose challenges to certain people—and user agents acting on their behalf. + +This specification aims to address the challenge of making sites more easily navigable for both people (particularly those facing accessibility barriers) and machines. It does this by standardising machine-readable names for common page types. User Agents can then query as to which destinations are supported on a given site (or page of that site), and present this information in an appropriate way for the user. + +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. + +The motivating use cases, "option 1" approach (using Well-known URIs), and an example end-user UI, are depicted in [our Well-known destinations AC 2024 lightning talk](https://w3c.github.io/adapt/presentations/ac2024/). + +## Motivating Use Cases + +* Supporting people facing cognitive accessibility barriers in navigating sites. + + - This includes mechanisms that can support clear signposting within a User Agent to "standard" or "common" areas of sites that users wish to visit—e.g. "log in", "products", or the site's accessibility statement. + + - This also includes supporting users and accessibility auditors in quickly discovering the accessibility statement for a site. + +* Allowing UAs, or other machines, acting on behalf of users to also find common areas of sites. + +## Out of scope + +* Specifying the contents of well-known pages, nor the schema of any data to be found in one of the common areas of the site, when they are accessed by machines. + +* Specifying the way in which supported well-known pages are displayed to the user. + +* Specifying the interface within the UA (or UA extension) by which the user can navigate to supported well-known pages. + +Though out of scope, an proof-of-concept UI for enumerating a site's well-known 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 well-known destinations offered by the site: home, accessibility statement, contact, help, log in, and products.](../presentations/ac2024/ext02.png) + +## User research + +Our proposed "well-known destinations" come from work done by the [Cognitive and Learning Disabilities Accessibility Task Force](https://www.w3.org/WAI/GL/task-forces/coga/). + +> [!NOTE] +> This is not a complete list—we are consulting with COGA to update the [destinations that the WAI-Adapt TF inherited from COGA](https://raw.githack.com/w3c/adapt/CR-content-2022-07-26/content/index.html#values-0). + +An illustrative set of proposed well-known destinations is as follows... + +* `accessibility-statement` (for the site's [accessibility statement](https://www.w3.org/WAI/planning/statements/)) + +* `change-password` (as per [A Well-known URL for Changing Passwords](https://www.w3.org/TR/change-password-url/)) + +* `help` (for the site's main help landing page) + +* `log-in` + +* `products` (for the site's main product section's landing page) + +* `search` (intended for a dedicated search page; a [`search` landmark region](https://www.w3.org/TR/wai-aria-1.2/#search) would be used on any page that contains a search form) + +## Well-known destinations: technical requirements + +We are investigating two technical approaches to supporting the above user needs. Both approaches have common elements. All approches that would solve these user needs must provide the following. + +* A way to denote the scope of any particular site (or sub-site). + +* A way to represent each well-known destination proposed above. + +* A mechanism for discovering all well-known destinations supported by a site—to be used when a UA first visits a site on behalf of the user. In order to do this efficiently, it must be possible to make this query in a single HTTP request. The results would be available to the user via the UI of the UA. + +* A procedure for visiting a well-known destination directly (when the user activates the interface in the UA). + +* A mechanism by which a well-known destination would be updated (by the content author). + +* Means to identify when a link on a page takes the user to a sub-page of a well-known destination page. E.g. a link to the "help on logging in" page (as opposed to the main "help" section landing page, which is where the well-known destination alone would take the user). + +The following features are also very desirable, but may be deferred to a later version of the spec: + +* Means to demarcate an element on the destination page that provides the destination content. + +## Option 1: Well-known URIs, and HTML link types + +This approach builds on: + +* Well-known URIs to identify destination pages—with a small extension (detailed in [enumerating well-known destinations](#enumerating-well-known-destinations) below) to support efficient polling of destinations; and + +* HTML link relation types to identify when links point to well-known destinations. + +### The well-known destination namespace + +As there are several destinations that could be provided by a site, they will be namespaced under the following parent well-known URL. + + /.well-known/ia/ + +Under this namespace are the following proposed URLs (the purpose of each is given in the [user research](#user-research) section above). + +* `/.well-known/ia/accessibility-statement` + +* `/.well-known/ia/change-password` + +* `/.well-known/ia/help` + +* `/.well-known/ia/log-in` + +* `/.well-known/ia/products` + +* `/.well-known/ia/search` + +The namespace has been specified as `/.well-known/ia/`, with "ia" standing for "information architecture". This term matches clauses 2, 4, and 8 of [the definition of "information architecture" as given by Wikipedia](https://en.wikipedia.org/wiki/Information_architecture#Definition). Clause 2 states: + +> The art and science of organizing and labeling web sites, intranets, online communities, and software to support findability and usability. + +Other options instead of "ia" were considered, including "information-architecture", "structure", and others. However "ia" was both felt to be accurate, and is more concise than the other alternatives. + +### Defining a site + +Well-known URLs work on the basis of _origins_. + +If a site is organised in such a way to have sub-sites that are at subdomains, this will work as intended—the destinations for each sub-site will be reflected separately. + +However, if the overall site is organised such that sub-sites are rooted at different URL paths, this will not be the case. + +> [!NOTE] +> We are investigating: +> +> * How much of a barrier this may be. +> +> - How many sites may be affected. +> +> - How problematic it may be for users to have to visit a landing page that provides links to sub-site-specific pages. +> +> * Ways that this could be overcome (other than having the well-known destination point to a landing page that provides onward links to sub-site pages). + +### Enumerating well-known destinations + +> [!IMPORTANT] +> This section describes a behavior that would need to be specified as an extension to Well-known URIs. + +When a UA requests the root URL for the information architecture namespace: + + /.well-known/ia/ + +A JSON string is returned that represents the list of well-known destinations this site provides. For example, if the site provided a page to allow users to sign in to their accounts, and an accessibility statement, then the returned JSON string would be: + +```json +["accessibility-statement","log-in"] +``` + +The UA would then be able to present this information to the user in some way. We envisage that, initially, this could be done via a browser extension that provides a pop-up (or sidebar) that would list the available destinations on the site in a localised manner for the user. In this case, that list might be: + +* Accessibility statement + +* Log in + +### Visiting a well-known destination directly + +This would normally happen when the user activates a control in the UA's (or UA extension's) interface to trigger visiting the particular destination. + +1. UA requests the well-known URL directly. + +2. Depending on whether the URL exists… + + 1. **If the URL exists:** a redirect is given, and the actual page loads normally (assuming the "real" URL given in the redirect is valid). + + 2. **If the URL does not exist:** A 404 response is received. In this case, the UA would display the 404 page…this is unlikely to happen in normal use (because supported destinations would've already been queried), and may indicate that the site is mis-configured. + +### Updating a well-known destination + +When the "real" URL to which a well-known URL points is changed (because the page is moved/deleted), then the well-known URL redirect must be updated, or removed entirely. + +### Expressing when a link points to part of a well-known destination + +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 well-known destination (e.g. the "Help" landing page, vs "Help on logging in") becuase it knows the URL of the root of the well-known destination, via the discovery process above. + +### Demarcating destination content + +> [!NOTE] +> We have not completed this feature yet. + +## Option 2: Linksets, and HTML link types, and one Well-known URI + +This approach builds on: + +* Linksets to identify destination pages—with a small "extension" (or, rather, difference in how the linkset is interpreted—detailed in [defining a site](#defining-a-site-1) below) for defining sub-sites; + +* A single Well-known URI from which the linkset would be served; and + +* HTML link relation types to identify when links point to well-known destinations. + +### The well-known destination namespace + +Each destination is part of a vocabulary. As there are several destinations that could be provided by a site, they will be namespaced under a root vocabulary namespace, for example (taking inspiration from GS1's vocabulary)... + + https://w3.org/voc/ia/ + +Under this namespace are the following proposed URLs (the purpose of each is given in the [user research](#user-research) section above). + +* `https://w3.org/voc/ia/accessibility-statement` + +* `https://w3.org/voc/ia/change-password` + +* `https://w3.org/voc/ia/help` + +* `https://w3.org/voc/ia/log-in` + +* `https://w3.org/voc/ia/products` + +* `https://w3.org/voc/ia/search` + +The namespace has been specified as `https://w3.org/voc/ia/`, with "ia" standing for "information architecture". This term matches clauses 2, 4, and 8 of [the definition of "information architecture" as given by Wikipedia](https://en.wikipedia.org/wiki/Information_architecture#Definition). Clause 2 states: + +> The art and science of organizing and labeling web sites, intranets, online communities, and software to support findability and usability. + +Other options instead of "ia" were considered, including "information-architecture", "structure", and others. However "ia" was both felt to be accurate, and is more concise than the other alternatives. + +### Defining a site + +> [!IMPORTANT] +> This section describes a semantic that would need to be interpreted differently when interpreting a "well-known" linkset. + +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. + +```json +{ "linkset": + [ + { "anchor": "https://acme.biz/", + "https://w3.org/voc/accessibility-statement": [ + { "href": "https://acme.biz/accessibility" } + ], + "https://w3.org/voc/help": [ + { "href": "https://acme.biz/support" } + ], + "https://w3.org/voc/log-in": [ + { "href": "https://acme.biz/sign-in" } + ] + } + ] +} +``` + +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 well-known destinations would interpret the `anchor` field in a specific way:** Well-known 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. + +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. + +* A "root" site (for the hotel as a whole) at `acme.hotel`. + +* The main hotel website provides an overall `accessibility-statement` and `log-in` destination, and a `contact` destination for the hotel (mainly intended for room bookings). + +* There is a "restaurant" micro-site that has its own `contact` page (but inherits the root site's `accessibility-statement` and `log-in` pages). + +* There is a "gym" micro-site that has its own `contact` page (but inherits the root site's `accessibility-statement` and `log-in` pages). + +```json +{ "linkset": + [ + { "anchor": "https://acme.hotel/", + "https://w3.org/voc/accessibility-statement": [ + { "href": "https://acme.hotel/accessibility" } + ], + "https://w3.org/voc/contact": [ + { "href": "https://acme.hotel/contact" } + ], + "https://w3.org/voc/log-in": [ + { "href": "https://acme.hotel/sign-in" } + ] + }, + { "anchor": "https://acme.hotel/restaurant", + "https://w3.org/voc/contact": [ + { "href": "https://acme.hotel/restaurant/contact" } + ] + }, + { "anchor": "https://acme.hotel/gym", + "https://w3.org/voc/contact": [ + { "href": "https://acme.hotel/gym/contact" } + ] + } + ] +} +``` + +In this case, the UA would need to interpret the URL structure of the linkset as a tree, and ensure that, when the user is visiting the gym's sub-site, for example, the gym's `contact` page is recognised, but the overall root (hotel) site's `accessibility-statement` would apply. + +> [!NOTE] +> The way that the UA presents the underlying tree structure of destinations across the root and sub-sites is out of scope. We envisage a range of UAs, or user preference settings, being created to cater for differing user needs. + +### Enumerating well-known destinations + +The first time the user visits the origin, the linkset for the origin, and sub-sites, would be fetched from a well-known URI, such as `/.well-known/ia/linkset`. + +> [!NOTE] +> We need to investigate how, on a large site, the linkset documents could be split up to improve performance and/or ease of editing, in the event different teams work on different sub-sites. + +### Visiting a well-known destination directly + +* The user selects the well-known destination in the UI of their UA. + +* The corresponding URL is loaded. + +If a destination isn't supported, the UI is expected to _not_ include it. + +### Updating a well-known destination + +The content author would need to update the linkset file, and replace it on the server. + +> [!NOTE] +> We need to investigate how, on a large site, the linkset documents could be split up to improve performance and/or ease of editing, in the event different teams work on different sub-sites. + +### Expressing when a link points to part of a well-known destination + +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 well-known destination (e.g. the "Help" landing page, vs "Help on logging in") becuase it knows the URL of the root of the well-known destination, via the discovery process above. + +### Demarcating destination content + +> [!NOTE] +> We have not completed this feature yet. + +## Security \& Privacy considerations + +> [!NOTE] +> We have not completed this section yet. + +## Considered alternatives + +### Sitemaps + +[Sitemaps](https://www.sitemaps.org/) are intended to solve different problems than this work. + +* Sitemaps are intended to enumerate all major (and possibly minor) pages; our goal here is to highlight specific common pages that may be provided. + +* Sitemaps do not give standard names to certain types of pages; our goal here is to semantically identify the purpose of specific pages, so that the UA can present this information to the user, and so that machines can reach certain pages. + +It does not seem like a good fit to try to extend the format of sitemaps to accommodate these requirements. + +### Using `rel` attribute values alone + +Using `rel` attribute values is part of the proposed spec—for cases where deep links may be provided into an overall well-known section (e.g. help on a specific topic). + +It would be possible to use _only_ `rel` values to highlight well-known destinations (if they were applied to links to the top-level destination landing pages, and there was a way to denote that a link was to the top-level destination landing page), but this would have the disadvantage that the overall destinations for a particular site could not be determined, nor presented to the user, in a simple and robust way. The user could only discover them if they landed on the right pages. + +This would pose the risk that the interface presented by the UA would not give a complete picture of what is available on the site, and thus either not be of great use, or—worse—be actively confusing for people to use. + +> [!NOTE] +> Open questions: +> +> * How often would footer links cover this? (If often, does that negate the need for this spec?) +> +> * What is the performance cost of parsing all those `rel` attributes every time? (This would be required if the `rel` approach were to be used at all.) + +## Stakeholder feedback/opposition + +> [!NOTE] +> We are actively involved in early discussions with some stakeholders, and will seek wide review as soon as possible. + +## References \& acknowledgements + +* The WAI-Adapt TF + +* Abhinav Kumar + +* Léonie Watson + +* Phil Archer + +* The COGA TF + +### Foundational work + +#### Destinations + +* [Destinations that Adapt inherited from COGA](https://raw.githack.com/w3c/adapt/CR-content-2022-07-26/content/index.html#values-0) + +> [!NOTE] +> As mentioned above, the destinations are under review. + +#### Well-known URLs + +* [IETF's Well-Known URIs RFC](https://www.rfc-editor.org/rfc/rfc8615) + +* [IANA's well-known URI registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml) + +* W3C's [A Well-Known URL for Changing Passwords](https://www.w3.org/TR/change-password-url/) specification (the URL for which is lodged in IANA's registry) + +#### Linksets + +* [IETF's Linksets RFC](https://www.rfc-editor.org/rfc/rfc9264) + +* [GS1's linkset visualisation demo](https://gs1.github.io/linkset/) + +#### Link types/relations + +* HTML's [standard link types](https://html.spec.whatwg.org/multipage/links.html#linkTypes) + +* Extended link types (also known as "link relations"): + + - [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)