diff --git a/help/index.html b/help/index.html index 5bf02796..f677b4bb 100644 --- a/help/index.html +++ b/help/index.html @@ -1,343 +1,53 @@ - - - - - - - - -WAI-Adapt: Help and Support Module - - - - - - - - - - - - - -
-

-

WAI-Adapt: Help and Support Module

-

W3C Editor's Draft

-
- More details about this document -
-
This version:
- https://w3c.github.io/adapt/content/ -
-
Latest published version:
- https://www.w3.org/TR/adapt-help/ -
-
Latest editor's draft:
https://w3c.github.io/adapt/content/
-
History:
- https://www.w3.org/standards/history/adapt-help/ -
- Commit history -
- - - - - -
Editors:
- -
- (Benetech) -
- (Invited Expert) -
- (W3C) -
- (W3C) -
- Richard Schwerdtfeger (Knowbility) (Editor until October 2017) -
- - -
Feedback:
- GitHub w3c/adapt - (pull requests, - new issue, - open issues) -
- - -
-
- - -

- Copyright - © - 2021-2024 - - World Wide Web Consortium. - W3C® - liability, - trademark and - document use rules apply. -

-
-
-

Abstract

+ + + +

This specification provides web content authors a standard approach to support web users who are persons with various cognitive and learning disabilities, including users who require:

-

This WAI-Adapt: Help and Support Module is a component of the WAI-Adapt series introduced in the WAI-Adapt Explainer document [personalization-semantics-1.0].

+

This WAI-Adapt: Help and Support Module is a component of the WAI-Adapt series introduced in the WAI-Adapt Explainer document [[personalization-semantics-1.0]].

-

Status of This Document

This section describes the status of this - document at the time of its publication. A list of current W3C - publications and the latest revision of this technical report can be found - in the W3C technical reports index at - https://www.w3.org/TR/.

- This document was published by the Accessible Platform Architectures Working Group as - an Editor's Draft. -

Publication as an Editor's Draft does not - imply endorsement by W3C and its Members.

- This is a draft document and may be updated, replaced or obsoleted by other - documents at any time. It is inappropriate to cite this document as other - than work in progress. - -

- - This document was produced by a group - operating under the - W3C Patent - Policy. - - - W3C maintains a - public list of any patent disclosures - made in connection with the deliverables of - the group; that page also includes - instructions for disclosing a patent. An individual who has actual - knowledge of a patent which the individual believes contains - Essential Claim(s) - must disclose the information in accordance with - section 6 of the W3C Patent Policy. - -

- This document is governed by the - 03 November 2023 W3C Process Document. -

+
-

1. Introduction

This section is non-normative.

- -

1.1 Background

- +
+

Introduction

+
+

Background

This document lists examples of the personalized help and support properties, this is an extension of WAI-Adapt Explainer, including the properties of literal, numberfree, easylang, alternative, explain, feedback, moreinfo, extrahelp, helptype.

-

1.2 WAI-Adapt: Help and Support Module

- -

WAI-Adapt: Help and Support Module is the second part of the WAI-Adapt technical specification, which provides WAI-Adapt and vocabularies that can be used to mark-up web content with additional semantic information, enabling user agents to augment or adapt content to various user-scenarios based on the user’s personalization settings or preferences. User agents use these semantics to augment or provide alternative content tailored to the user’s specific needs — for example, a user 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.

+
+

WAI-Adapt: Help and Support Module

+

WAI-Adapt: Help and Support Module is the second part of the WAI-Adapt technical specification, which provides WAI-Adapt and vocabularies that can be used to mark-up web content with additional semantic information, enabling user agents to augment or adapt content to various user-scenarios based on the user’s personalization settings or preferences. User agents use these semantics to augment or provide alternative content tailored to the user’s specific needs — for example, a user 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.

-

1.3 Vocabulary Structure and Implementations

- +
+

Vocabulary Structure and Implementations

All the vocabulary in WAI-Adapt: Help and Support Module is constructed of properties and their values. Please see our WAI-Adapt Explainer.

The vocabulary implementations included in this document are available at our implementations wiki page.

-

1.3.1 Properties

- +
+

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.

-

1.3.2 Values

- +
+

Values

Values provide the specific personalization 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
@@ -359,1119 +69,49 @@

WAI-Adapt: Help and Support Module

Note that the attributes and values in this specification do not 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.

-
Editor's note
Since implementations have not yet been finalized, any examples in this document are illustrative only, and are provided to help in understanding the concept. All examples will be updated once implementation examples are finalized.
+
Since implementations have not yet been finalized, any examples in this document are illustrative only, and are provided to help in understanding the concept. All examples will be updated once implementation examples are finalized.
-

1.4 Use Cases and Requirements

- +
+

Use Cases and Requirements

The Requirements for Personalization Semantics describes use cases and requirements. This module provides properties to fulfill those requirements related to adapting content.

-

2. Terms

- +
+

Terms

This document uses a number of specific terms related to various cognitive disabilities and related user-needs. Those terms have been defined by the Cognitive and Learning Disabilities Accessibility Task Force. See the COGA Glossary for specific definitions.

-

3. Vocabulary

- -

3.1 vocabulary

- -

3.1.1 Description

- -
-

The following are property terms used to describe alternative or supportive content that may be useful for people with disabilities. The current list focuses on cognitive disabilities, hover we intended to merge the vocabularies for other disabilities in the next version.

-

Overview of supported values: -

-
    -
  • On text: active, chunks, dictionary, easylang, explain, faqs, glossary, humanhelp, literal, moreinfo, numberfree, simplified, smallsentences, thesaurus, vocab500, vocab1000, vocab2000
    • -
  • General: alternative, automated, helpforms, largefont, lessoptions, symbolic, whitespace
    • -
  • Images: p0, p1, p2, p3, realistic, symbolic
    • -
-

Note that there is no default value.

-
-
- -

3.1.2 Values for alternative content and content accessibility support

- -
Editor's note
This focuses on cognitive accessibility. We may add other collections from https://github.com/w3c/personalization-semantics/wiki/User-needs-collections such as https://www.w3.org/wiki/WebSchemas/Accessibility.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
easy-lang-chunksBreaks content up into smaller sections with a single topic per section.
easy-lang-allProvides an alternative version or rewrites the default content for easier comprehension. This may include: -
  • chunking
    • -
  • simple tense (used to describe actions without specifically stating whether the actions are completed or ongoing.)
    • -
  • simple voice
    • -
  • clear text
    • -
  • clear
    • -
  • usage of short sentences
    • -
  • summary of long documents
-
less-optionsProvide fewer choices by combining related choices together.
literal-imageprovide the literal translation of existing casual language or idioms.
image-supplementary

symbol or illustration that is typically shown with alt=""

-

extra illustration that will not distract most people such as at the start of a paragraph or option

-

disability centric illustrations that can disturb other people and may be mid-sentence.

-
realistic-imageprovides a realistic version of a stylized or cartoonish (not real) image.The opposite of symbolic.
simplified-langProvides, a version of the content that is easier to read and understand. Includes easylang and lessOptions
easy-lang-small-sentencesprovides a version of the content with shorter sentences and simple language.
symbolicprovides an alternative, symbolic representation of an image, for example a picture rather than a photograph.The opposite of realistic.
vocab1000Terms are limited to a core vocabulary of up to 1000 words - unless terms are defined using easy language
vocab2000Terms are limited to a core vocabulary of upto 2000 words- unless terms are defined using easy language
vocab500Terms are limited to a core vocabulary of upto 500 words- unless terms are defined using easy language
white-spaceadd additional whitespace between characters, words, and rows.
interoprable-symbolsInteroperable symbol sets are supported.
interoprable-controlsInteroperable controls and regions are supported.
user-testedCore tasks, including submitting all forms, contacting help and feedback, have been successfully tested with people with memory, language, and numeracy impairments.
understandable-designFollows the design for understandable design such as theme 1 in https://docs.google.com/document/d/1WcfVALVq8PS9CLXUuAfV9Op0wXvI2yJYedj5jO23GTk/edit#. Must included: Must include: making each section of a content clear,using hierarchal grouping, consistent back functionality, and consistently visually clear controls.
human-focusFollows the design for helping people keep focus such as theme 3 in https://docs.google.com/document/d/1WcfVALVq8PS9CLXUuAfV9Op0wXvI2yJYedj5jO23GTk/edit# Must include that: -
  • 1. there are no interruptions or interruptions can be easily turned off via one action or via an operating system setting.
    • -
  • 2. Purpose of each screen is clear.
useable-authenticationFollows the design for authetification such as theme 4 in https://docs.google.com/document/d/1WcfVALVq8PS9CLXUuAfV9Op0wXvI2yJYedj5jO23GTk/edit#. Must included that Logging in does not rely on good memory or other cognitive skills.
useable-menusFollows the design for authentication such as theme 4 in https://docs.google.com/document/d/1WcfVALVq8PS9CLXUuAfV9Op0wXvI2yJYedj5jO23GTk/edit#. Must support the ability that voice menus can be avoided in voice interfaces (alternative mechanism), and clear hierarchical menus and search is available in visual interfaces.
support-APIBrowser extensions and APIs are supported
help-and-supportFollows the design for understandable design such as theme 5 in https://docs.googlecom/document/d/1WcfVALVq8PS9CLXUuAfV9Op0wXvI2yJYedj5jO23GTk/edit#. Must include that Content and information is provided that helps users understand complex information, long documents, numerical information, relative and cardinal directions (North, South, East, and West), forms and non-standard controls. Where an understanding of mathematics is not a primary requirement for using this content, reinforce numbers with non-numerical values
reminders-and-stepsModule 4 is supported
no-data-lossForms do not timeout or data is not lost if the site times out for at least one week. Or provides information about all the information you might need and the time out.
-
- -

3.1.3 Values for types of help

- -
Editor's note
This may be added to or harmonized with link destinations in module 1. Or it may be added to the above table.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
automated-stepProvides an alternative step by step sequence for completing a task or procedure.
automated-botProvides an automated conversational help. Typically designed to look like human help.
dictionaryProvides a definition of the term or topic. May redirect to another URI or provide the information in-line, via a popup, or other method.
faqsRedirects to a FAQ page with the related topic in view.
glossaryProvides a URI to a glossary page with the related topic in view.
helpformUsed with forms when the user may need more or simplified information about the type of information being requested. Provides access/reference to a modified form with more information about each requested item.
humanhelpProvides the user with access to human help. This may be through a live chat, providing a phone number to call for human assistance, or other mechanism to reach a person for direct assistance.
morehelpProvides a more detailed explanation about the current topic or process.
moreinfoProvides additional levels of detail.
simplifiedPropose this should be easylang rather than simplified. Provides, a version of the content that is easier to read and understand.
thesaurusProvides a list of synonyms for the current term. May redirect to another uri or provide a list of synonyms in-line, via a popup, or other method.
tooltipsoffers an option of adding tooltips to provide morehelp with more detailed information about the current topic or process.
topic-searchprovides a uri for the user to perform a search on the current topic with the suggested search term included.
explainProvides a more detailed description of a process or term.
extra-helpAdditional information about the current action or process in one or more formats.
hide-timerProvides a mechanism to hide the countdown clock in timed situations. For example, a timed exam.
statusImmediately provides and identifies information about an action that has occurred.
trigger-warningProvides a label for content that may cause traumatic response.
useable-feedbackFollows the design for understandable design such as theme 6 in https://docs.googlecom/document/d/1WcfVALVq8PS9CLXUuAfV9Op0wXvI2yJYedj5jO23GTk/edit#. Must include tat Feedback is usable by each core useability group.
-
- -

3.1.4 Characteristics

- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:landmarks and regions in Divs and sections, alternative (in headers) some cases alt text
Value:token list
-
- - - -
- +
+

Vocabulary

+
-

4. Example Implementations

- -

The Working Group is currently exploring different methods of implementing help and support in the context of the Personalization effort. The following examples are for illustration only, to assist in visualizing how this may work. The examples illustrate "large" amounts of alternative content, contained inline but hidden from traditional views. This content would be exposed to the end user on demand. For smaller pieces of content, additional information and support can be provided inline within the relative context of the content.

-
Editor's note

Currently all examples are implemented through attribute/value pairs. This does not imply that attribute/value pairs are the only implementation strategy. The Working Group plans to add additional examples using other mechanisms as previously indicated.

-

4.1 Implementation in different content sections

- -

4.1.1 Alternative

- -
4.1.1.1 Description
- -
-

Would be used on an alternative content as an alternative to more detailed or difficult to understand content. alternative can be used on a span, div, link or image that servers as alternative content to it's direct parent element.

-
Editor's note

This data model may be too complex, so this property could undergo substantial changes.

-

Supported values: -

-
    -
  • On text: easylang, explain, more, vocab500, vocab1000, vocab2000, active, literal, numberfree, smallsentences, chunks
    • -
  • General: lessoptions. Whitespace, largefont
    • -
  • Images: symbolic , realistic
    • -
  • p0, p1, p1, p2, p3 Where p0 are images with true content, p1 is a symbol or illustration that is typically shown with alt="", P2 are extra illustration that most people will not mind such as at the start of a paragraph or option. p3 are for disability centric illustrations that can disturb other people and may be mid sentence.
    • -
-

Note that there is no default value.

-
-
-
4.1.1.2 Example
- -

The below example section show how alternative used when coding.

-
-
- Example 1: alternative using adapt- - 
    <div>
-	<span adapt-alternative="easylang numberfree vocab1000" class="hidden">
- 	   most people prefer simple text
-  	</span>
-        In studies it was found that only 30% of users prefer long convoluted text
-  	with obtuse words and lots of numbers,
-  	with 56% claiming there preferred the simplified text,
-  	with the remainder unsure or stated it depends on the context.
-</div>
-
- -
-
4.1.1.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:token list
-
-
- -

4.1.2 helptype

- -
4.1.2.1 Description
- -
-

Would be used on additional content to indicate the type of extra help provided. helptype can be used on a span, div, link or image that provides or redirects the user to additional help information.

-

Overview of supported values: -

-
    -
  • On text: dictionary, faqs, glossary, humanhelp, literal, morehelp, simplified, thesaurus, vocab500, vocab1000, vocab2000
    • -
  • General: automated, helpform, largefont, lessoptions, symbolic, tooltips, whitespace
    • -
  • Images: p0, p1, p2, p3, realistic, symbolic
    • -
-

Note that there is no default value.

-
- -
-
4.1.2.2 Example
- -

The below example section show how helptype used when coding.

-
-
- Example 2: helptype using adapt- - 
    <button type="button" adapt-extrahelp="uri2 uri3" >undo</button>
-
-
-URI 2 may read: 
-
-
-    <div id="uri2" adapt-helptype="morehelp" adapt-hidden="true">
-        pressing the undo button will erase all your work on this page.
-        Use this button with care.
-        If you press it by mistake, press control and y at the same time
-        and your answers will come back.
-    </div>
-
-<a href="functiongethelp()" adapt-helptype="humanhelp" adapt-hidden="true">
-  I want a person to help me</a>
-
-<div id="uri3" adapt-extrahelp="glossary" adapt-hidden="true">
-
- -
- -
4.1.2.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:token
-
-
- - +
+

Example Implementations

+

The Working Group is currently exploring different methods of implementing help and support in the context of the Personalization effort. The following examples are for illustration only, to assist in visualizing how this may work. The examples illustrate "large" amounts of alternative content, contained inline but hidden from traditional views. This content would be exposed to the end user on demand. For smaller pieces of content, additional information and support can be provided inline within the relative context of the content.

+

Currently all examples are implemented through attribute/value pairs. This does not imply that attribute/value pairs are the only implementation strategy. The Working Group plans to add additional examples using other mechanisms as previously indicated.

+
+

Implementation in different content sections

+
+
-

4.2 Inline Implementation

- +
+

Inline Implementation

For small inline support and changes, attributes may be used.

-

4.2.1 literal

- -
4.2.1.1 Description
- -
-

literal provides alternative text for people who prefer content that does not use non literal text, such as metaphors.

-

A personalization agent may replace the content with the literal alternative, or it may put the literal alternative in a tooltip.

-

User agents may also render non-literal text in a different way so that users will be able to identify non literal content. They can then use a mouse over or other technique to receive the alternative.

-

A user agent must be able to replace the non literal content with the literal alternative without loss of meaning.

-

Supported value: String text

-

Note that there is no default value.

-
-
-
4.2.1.2 Example
- -

The below example section show how literal used when coding.

-
-
- Example 3: literal using adapt- - 
It is <span adapt-literal="raining hard">raining cats and dogs</span>
-
-
-
4.2.1.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:Alt text
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
-
-
- - - - - -

4.2.2 numberfree

- -
4.2.2.1 Description
- -
-

numberfree provides alternative text for people who prefer content that does not use numerical concepts.

-

A personalization agent may replace the content with the number free alternative, or it may put the number free alternative in a tooltip or sidebar. The content must still be understandable when a user agent replaces the original content with the number free alternative.

- -

Supported value: String

-

Note that there is no default value.

- -
-
-
4.2.2.2 Example
- -

The below example section show how numberfree used when coding.

-
-
- Example 4: numberfree using adapt- - 
<span adapt-numberfree="almost all">9 out of 10 </span>
-
- -
-
- Example 5: numberfree using adapt- - 
<span adapt-numberfree="hat and coat weather">The weather is 9 degrees</span>
-
-
-
4.2.2.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:Alt text
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string
-
-
- - - - - -

4.2.3 easylang

- -
4.2.3.1 Description
- -
-

easylang provides an alternative text of the content that is easier to read and understand. Note that this only works on small sections of text as the easylang attribute does not support full HTML, such as lists and tables.

-

A personalization agent (3rd-party tool or browser extension) may replace the content with the simpler alternative, or it may put the alternative in a tooltip or help panel.

-

User agents may also render hard text in a different way so that users will be able to identify text that has an alternative provided.

-

The content must still be understandable when a user agent replaces the original content with the simpler alternative.

-

Supported values: String text

-

Where easylang should use as simple well-known words as possible, and active voicing, literal text, small simple sentences. Acronyms and abbreviations should be avoided, unless they are the common way to refer to an item.

-
-
-
4.2.3.2 Example
- -

The below example section show how easylang used when coding.

-
-
- Example 6: easylang using adapt- - 
<span adapt-easylang="some text that is easy to read"> some convoluted obtuse text</span>
-
-
-
4.2.3.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts: Alt text
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
-
-
- - - - - -

4.2.4 explain

- -
4.2.4.1 Description
- -
-

This attribute provides any information that helps the user anticipate the functionality, such as letting the user know what behavior will trigger an event. This is most important if the mechanism is not standard.

-

User experience: This help can be rendered as a tool tip, help link or read when the control or link is read. Most users will not want this text rendered or spoken, but other users however will need it to understand the behavior of the element.

-

Note that there is no default value.

-

These values will change when the email is sent.

-
-
-
4.2.4.2 Example
- -

The example section below shows how explain used when coding.

-
-
- Example 7: explain using adapt- - 
adapt-explain="press enter to send the email"
-
- -
-
4.2.4.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
-
-
- - - - - -

4.2.5 feedback

- -
4.2.5.1 Description
- -
-

This attribute provides immediate feedback that can be shown or spoken when any event is triggered on a control.

-

User experience: This can be rendered as text at the top of the page and read immediately. Most users will not want this text rendered and spoken. Other users however will need it to know what has just happened.

-
-
-
4.2.5.2 Example
- -

The example section below shows how feedback might be used when coding.

-
-
- Example 8: feedback using adapt- - 
adapt-feedback="your email on %topic% was sent"
-
- -
-
4.2.5.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
-
-
- - - - - -

4.2.6 moreinfo

- -
4.2.6.1 Description
- -
-

moreinfo provides users access to additional information about the current content in one of several formats.

-

A personalization agent may add additional explanatory text or provide an action for the user to take to obtain more detailed information about the content.

-

Supported values: URI

-

Note that there is no default value.

-
- -
-
4.2.6.2 Example
- -

The example section below shows how moreinfo would be used when coding.

-
-
- Example 9: moreinfo using adapt- - 
N/A - Example needed.
-
- -
-
4.2.6.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:URI
-
-
- -

4.2.7 extrahelp

- -
4.2.7.1 Description
- -
-

extrahelp provides users access to additional information about the current action or process in one or more formats.

-

A personalization agent may add additional explanatory text or provide an action for the user to take to obtain more detailed information or assistance in completing a task

-

Supported values: URI

-

Note that there is no default value.

-
- -
-
4.2.7.2 Example
- -

The example section below shows how extrahelp would be used when coding.

-
-
- Example 10: extrahelp using adapt- - 
N/A - Example Needed
-
- -
-
4.2.7.3 Characteristics
- - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:URI
-
-
- +
+
+
+
+
+
+
- -

5. Privacy and Security Considerations

- -

This specification adds context information about content to the document, and should not affect security.

-

Although this specification does not expose personal preferences and personal information, third party user agents or proxy server(s) acting upon our semantic information may need to store personal preferences on how to present content to a specific user. It is recommended that any user agent or proxy server implements best practices to protect all personal preferences and personal information.

+
+
+

Privacy and Security Considerations

+

This specification adds context information about content to the document, and should not affect security.

+

Although this specification does not expose personal preferences and personal information, third party user agents or proxy server(s) acting upon our semantic information may need to store personal preferences on how to present content to a specific user. It is recommended that any user agent or proxy server implements best practices to protect all personal preferences and personal information.

Any user agent with user settings are recommended to follow best practices to keep user information secure.

-

A. Acknowledgments

This section is non-normative.

- -

The following people contributed to the development of this document.

-

A.1 Participants active in the WAI-Adapt TF at the time of publication

- -
    -
  • Matthew Atkinson (TPG Interactive)
    • -
  • Mike Beganyi (TPG Interactive)
    • -
  • Thaddeus Cambron (Invited Expert)
    • -
  • Michael Cooper (W3C/MIT)
    • -
  • John Foliot (Invited Expert)
    • -
  • Becky Gibson (Knowbility, Inc.)
    • -
  • Charles LaPierre (Benetech)
    • -
  • Roy Ran (W3C/Beihang)
    • -
  • Janina Sajka (Invited Expert)
    • -
  • Lisa Seeman (Invited Expert)
    • -
  • Sharon Snider (IBM Corporation)
    • -
  • Lionel Wolberger (UserWay)
    • -
-
-

A.2 Other WAI-Adapt TF contributors, commenters, and previously active participants

- -
    -
  • Joanmarie Diggs (Igalia)
    • -
  • Richard Schwerdtfeger (Knowbility, Inc.)
    • -
  • Jason White (Educational Testing Service)
    • -
-
-

A.3 Enabling funders

- -

This publication has been funded initially under contract number ED-OSE-10-C-0067, then under contract number HHSP23301500054C, and now under HHS75P00120P00168. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Health and Human Services, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government. Some of the work on this project has also received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No.780529 and 643399.

-
-
- - - -

B. References

B.1 Informative references

- -
[DOM4]
- DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/ -
[personalization-semantics-1.0]
- WAI-Adapt Explainer. Lisa Seeman-Horwitz; Charles LaPierre; John Foliot; Michael Cooper; Ruoxi Ran; Richard Schwerdtfeger. W3C. 3 January 2023. W3C Working Group Note. URL: https://www.w3.org/TR/adapt/ -
[SVG2]
- Scalable Vector Graphics (SVG) 2. Amelia Bellamy-Royds; Bogdan Brinza; Chris Lilley; Dirk Schulze; David Storey; Eric Willigers. W3C. 4 October 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/SVG2/ -
-
\ No newline at end of file +
Acknowledgements placeholder
+ + diff --git a/tools/index.html b/tools/index.html index 82652487..d21d1222 100644 --- a/tools/index.html +++ b/tools/index.html @@ -1,22 +1,278 @@ - - - - WAI-Adapt: Tools Module - - - - - + + + +WAI-Adapt: Tools Module + + + + + + + - - -
+ + + + + + + + +
+

+

WAI-Adapt: Tools Module

+

W3C Editor's Draft

+
+ More details about this document +
+
This version:
+ https://w3c.github.io/adapt/content/ +
+
Latest published version:
+ https://www.w3.org/TR/adapt-tools/ +
+
Latest editor's draft:
https://w3c.github.io/adapt/content/
+
History:
+ https://www.w3.org/standards/history/adapt-tools/ +
+ Commit history +
+ + + + + +
Editors:
+ +
+ (Benetech) +
+ (Invited Expert) +
+ (W3C) +
+ (W3C) +
+ Richard Schwerdtfeger (Knowbility) (Editor until October 2017) +
+ + +
Feedback:
+ GitHub w3c/adapt + (pull requests, + new issue, + open issues) +
+ + +
+
+ + +

+ Copyright + © + 2022-2024 + + World Wide Web Consortium. + W3C® + liability, + trademark and + document use rules apply. +

+
+
+

Abstract

This specification provides web content authors a standard approach to support web users who are persons with various cognitive and learning disabilities, including users who:

  • may get overwhelmed with the volume of on-screen messages, and wishes to filter out low priority messages and concentrate on critical priority messages;
    • @@ -25,33 +281,67 @@

The technology described in this specification is intended to be used to programmatically transform the appearance of typical web content including form controls, icons, and other user interface elements into a rendering more familiar and comprehensible to an individual user. Use cases and relevant vocabulary terms are defined which allow user agents to augment or adapt content to better fit a particular user's particular needs. This helps users with varying needs to understand web content more readily, by simplifying the web interaction, or by avoiding forcing the user to grapple with unfamiliar representations they are ill equipped to comprehend.

-

This WAI-Adapt: Tools Module is a component of the WAI-Adapt series introduced in the WAI-Adapt Explainer document [[personalization-semantics-1.0]].

+

This WAI-Adapt: Tools Module is a component of the WAI-Adapt series introduced in the WAI-Adapt Explainer document [personalization-semantics-1.0].

-
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+ This document was published by the Accessible Platform Architectures Working Group as + an Editor's Draft. +

Publication as an Editor's Draft does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

-
-

Introduction

-
-

Background

-

This specification module enables authors to add semantic information about content at the element level, in order to indicate the priority level of a message for the individual user, or programmatically enumerate tasks that the user is required to complete, so that users who have memory issues can keep track of the steps previously completed. It is anticipated that multiple screen renderings (transformations) will be supported in order to meet the differing needs of different users. Final renderings — generated via helper apps or 3rd-party tools — will be ultimately defined by the user's configuration settings.

+

1. Introduction

This section is non-normative.

+ +

1.1 Background

+ +

This specification module enables authors to add semantic information about content at the element level, in order to indicate the priority level of a message for the individual user, or programmatically enumerate tasks that the user is required to complete, so that users who have memory issues can keep track of the steps previously completed. It is anticipated that multiple screen renderings (transformations) will be supported in order to meet the differing needs of different users. Final renderings — generated via helper apps or 3rd-party tools — will be ultimately defined by the user's configuration settings.

This document lists examples of the personalized tools properties, an extension of WAI-Adapt Explainer, including the properties of messageimportance, messagefrom, messagecontext, messagetime, and stepindicator.

-
-

WAI-Adapt: Tools Module

-

WAI-Adapt: Tools Module is the third and final part of the WAI-Adapt technical specification, which provides WAI-Adapt semantics and vocabularies that can be used to mark-up web content with additional semantic information, enabling user agents to augment or adapt content to various user-scenarios based on the user’s personalization settings or preferences. The Tools Module enhances web content by providing additional information about message importance (for filtering), and tracking multi-step activities. User agents can use these semantics to augment or adapt content to the user’s scenario — for example allowing for the prioritization or filtering of on-screen messages. This helps users with varying needs to filter content by providing support for managing distractions.

+

1.2 WAI-Adapt: Tools Module

+ +

WAI-Adapt: Tools Module is the third and final part of the WAI-Adapt technical specification, which provides WAI-Adapt semantics and vocabularies that can be used to mark-up web content with additional semantic information, enabling user agents to augment or adapt content to various user-scenarios based on the user’s personalization settings or preferences. The Tools Module enhances web content by providing additional information about message importance (for filtering), and tracking multi-step activities. User agents can use these semantics to augment or adapt content to the user’s scenario — for example allowing for the prioritization or filtering of on-screen messages. This helps users with varying needs to filter content by providing support for managing distractions.

-
-

Vocabulary Structure and Implementations

+

1.3 Vocabulary Structure and Implementations

+

All the vocabulary in WAI-Adapt: Symbols Module is constructed of properties and their values. Please see our WAI-Adapt Explainer.

The vocabulary implementations included in this document are available at our implementations wiki page.

-
-

Properties

+

1.3.1 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

+

1.3.2 Values

+

Values provide the specific personalization 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
@@ -73,28 +363,614 @@

Values

Note that the attributes and values in this specification do not 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.

-
Since implementations have not yet been finalized, any examples in this document are illustrative only, and are provided to help in understanding the concept. All examples will be updated once implementation examples are finalized.
+
Editor's note
Since implementations have not yet been finalized, any examples in this document are illustrative only, and are provided to help in understanding the concept. All examples will be updated once implementation examples are finalized.
-
-

Use Cases and Requirements

+

1.4 Use Cases and Requirements

+

The Requirements for Personalization Semantics describes use cases and requirements. This module provides properties to fulfill requirements related to user support tools.

-
-

Terms

+

2. Terms

+

This document uses a number of specific terms related to various cognitive disabilities and related user-needs. Those terms have been defined by the Cognitive and Learning Disabilities Accessibility Task Force. See the COGA Glossary for specific definitions.

-
-

Vocabulary

-
-
+

3. Vocabulary

+ +

3.1 All the Step Indicator Properties

+ + +

3.1.1 Step Indicator Usage

+ +
3.1.1.1 Description
+ +

The stepindicator defined values should be used whenever there is a sequence of + tasks that the user is required to complete, so that users who have memory issues can keep + track of the steps previously completed.



+

Note that there is no default value.

+ +
+
3.1.1.2 Example
+ +

Note, the specific mechanism to apply these defined values has not been decided:

+
+
+ Example 1: stepindicator using adapt- + 
<div adapt-stepindicator="book trip">
+  <div adapt-status="complete" aria-label="select flight" adapt-step="1" adapt-steplocation="uri" />
+  <div adapt-status="current" aria-label="book hotel" adapt-step="2" adapt-steplocation="uri" />
+  <div adapt-status="" aria-label="book car" adapt-step="3" adapt-steplocation="uri" />
+  <div adapt-status="" aria-label="purchase trip" adapt-step="4" steplocation="uri" />
+</div>
+
+
+
+or the step number can be implied by the DOM
+
+
+
+  <div adapt-stepindicator="book trip">
+    <div adapt-status="complete" aria-labelledby="select flight">
+      <a href="uri">Select flight</a>
+    </div>
+    <div adapt-status="current" aria-labelledby="book hotel">
+      <a href="uri">Book Hotel</a>
+    </div>
+    <div adapt-status="" aria-labelledby="book car">
+      <a href="uri">Book car</a>
+    </div>
+    <div adapt-status="" aria-labelledby="purchase trip">
+      <a href="uri">Purchase trip</a>
+    </div>
+  </div>
+
+
+
+
+ + + + + +

3.2 All the message properties

+ + +

3.2.1 messageimportance

+ +
3.2.1.1 Description
+ +
+

The messageimportance attribute is used to indicate the priority level of a message . This can be helpful for a person who gets overwhelmed with messages and filter out low messages and concentrate on critical priority messages.

+

Supported values: low, medium(Default), critical

+ +
+
+
3.2.1.2 Example
+ +

The specific mechanism to apply these defined values has not been decided

+
+
+ Example 2: messageimportance using adapt- + 
<div role="alert" adapt-messageimportance="medium">
+    It is your daughter's birthday tomorrow
+</div>
+
+ +
+
3.2.1.3 Characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:token
+
+
3.2.1.4 Values
+ + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
criticalTo be critical a message needs to be both urgent and content that the user is very likely to consider important. For example, a system may send a message that it is going to reboot in one minute to install updates.
medium (default)Important messages that needs the user's attention at their convenience. For example, a relatively important chat message.
lowA message that does not need time sensitive attention. For example, a typical chat message.
+
+
+ + + +

3.2.2 messagefrom

+ +
3.2.2.1 Description
+ +
+

The messagefrom attribute can be used to help identify who a message a user receives is from.

+

Supported values: a string value that identifies the sender of the message. If multiple names are used they can be separated by a comma.

+

Note that there is no default value.

+
+
+
3.2.2.2 Example
+ +

The specific mechanism to apply these defined values has not been decided

+
+
+ Example 3: messagefrom using adapt- + 
<div role="alert" adapt-messageimportance="low"
+    adapt-messagefrom="lisa seeman, lseeman">
+    I posted a new version on GitHub for you to review
+</div>
+
+
+
3.2.2.3 Characteristics
+ +

The specific mechanism to apply these defined values has not been decided

+ + + + + + + + + + + + + + + + + + + + + + + + + +
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
+
+
+ + + +

3.2.3 messagecontext

+ +
3.2.3.1 Description
+ +
+

The messagecontext attribute can help clarify where a message is coming from. Knowing who the message is from as well as in which context the message was written are both importent in understanding the meaning of the message received.

+

Supported values: a string value that identifies the location that makes this message relevant. Typical values are "home" and "work". If multiple locations are relevant they can be separated by a coma.

+

Note that there is no default value.

+
+
+
3.2.3.2 Example
+ +

The specific mechanism to apply these defined values has not been decided

+
+
+ Example 4: messagecontext using adapt- + 
<div role="alert"
+    adapt-messageimportance="low"
+    adapt-messagefrom="lisa seeman, lseeman"
+    adapt-messagecontext="work">
+    I posted a new version on GitHub for you to review
+</div>
+
+
+
3.2.3.3 Characteristics
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
+
+
+

3.2.4 messagetime

+ +
3.2.4.1 Description
+ +
+

The messagetime attribute helps clarify when the message was sent.

+

Supported values: 24 hour date time format. DD.MM.YEAR.HOUR.MM - DD.MM.YEAR.HOUR.MM where the second date is an optional exclusive expiry date.

+

Note that there is no default value.

+
+
+ +
3.2.4.2 messagetime
+ +

The specific mechanism to apply these defined values has not been decided

+

@@1-line description

+
+
+ Example 5: messagetime using adapt- + 
    <div role="alert"
+        adapt-messageimportance="medium"
+        adapt-messagefrom="my calender"
+        adapt-messagecontext="work"
+        adapt-messagetime="10.02.2017.00.00-16.02.2017.00.00">
+        Renew your driving license this week
+    </div>
+
+
+
+    <div role="alert"
+        adapt-messageimportance="critical"
+        adapt-messagefrom="my calender"
+        adapt-messagecontext="work"
+        adapt-messagetime="16.02.2017.00.00">
+        Renew your driving license ASAP
+    </div>
+
+
+
3.2.4.3 Characteristics
+ +

The specific mechanism to apply these defined values has not been decided

+ + + + + + + + + + + + + + + + + + + + + + + + + +
CharacteristicValue
Related Concepts:SVG [SVG2] and DOM [DOM4] active
Used in Roles:All elements of the base markup
Inherits into Roles:Placeholder
Value:string text
+
+
+
+ + + +
-
-

Privacy and Security Considerations

-

This specification adds context information about content to the document, and should not affect security.

-

Although this specification does not expose personal preferences and personal information, third party user agents or proxy server(s) acting upon our semantic information may need to store personal preferences on how to present content to a specific user. It is recommended that any user agent or proxy server implements best practices to protect all personal preferences and personal information.

+

4. Privacy and Security Considerations

+ +

This specification adds context information about content to the document, and should not affect security.

+

Although this specification does not expose personal preferences and personal information, third party user agents or proxy server(s) acting upon our semantic information may need to store personal preferences on how to present content to a specific user. It is recommended that any user agent or proxy server implements best practices to protect all personal preferences and personal information.

Any user agent with user settings are recommended to follow best practices to keep user information secure.

-
Acknowledgements placeholder
- - +

A. Acknowledgments

This section is non-normative.

+ +

The following people contributed to the development of this document.

+

A.1 Participants active in the WAI-Adapt TF at the time of publication

+ +
    +
  • Matthew Atkinson (TPG Interactive)
    • +
  • Mike Beganyi (TPG Interactive)
    • +
  • Thaddeus Cambron (Invited Expert)
    • +
  • Michael Cooper (W3C/MIT)
    • +
  • John Foliot (Invited Expert)
    • +
  • Becky Gibson (Knowbility, Inc.)
    • +
  • Charles LaPierre (Benetech)
    • +
  • Roy Ran (W3C/Beihang)
    • +
  • Janina Sajka (Invited Expert)
    • +
  • Lisa Seeman (Invited Expert)
    • +
  • Sharon Snider (IBM Corporation)
    • +
  • Lionel Wolberger (UserWay)
    • +
+
+

A.2 Other WAI-Adapt TF contributors, commenters, and previously active participants

+ +
    +
  • Joanmarie Diggs (Igalia)
    • +
  • Richard Schwerdtfeger (Knowbility, Inc.)
    • +
  • Jason White (Educational Testing Service)
    • +
+
+

A.3 Enabling funders

+ +

This publication has been funded initially under contract number ED-OSE-10-C-0067, then under contract number HHSP23301500054C, and now under HHS75P00120P00168. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Health and Human Services, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government. Some of the work on this project has also received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No.780529 and 643399.

+
+
+ + + +

B. References

B.1 Informative references

+ +
[DOM4]
+ DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/ +
[personalization-semantics-1.0]
+ WAI-Adapt Explainer. Lisa Seeman-Horwitz; Charles LaPierre; John Foliot; Michael Cooper; Ruoxi Ran; Richard Schwerdtfeger. W3C. 3 January 2023. W3C Working Group Note. URL: https://www.w3.org/TR/adapt/ +
[SVG2]
+ Scalable Vector Graphics (SVG) 2. Amelia Bellamy-Royds; Bogdan Brinza; Chris Lilley; Dirk Schulze; David Storey; Eric Willigers. W3C. 4 October 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/SVG2/ +
+
\ No newline at end of file