WAI-Adapt: Content Module

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:

Customarily communicate using symbolic languages generally known as Augmentative and Alternative Communications (AAC);
Need more familiar icons (and other graphical symbols) in order to comprehend page content;
Benefit from additional help resources;
Require a simplified page in order to interact successfully.

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. Providing additional help is supported, as is automated page simplification. 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, and by avoiding forcing the user to grapple with unfamiliar representations they are ill equipped to comprehend.

This WAI-Adapt: Content Module is a component of the WAI-Adapt series introduced in the WAI-Adapt Explainer document [adapt].

The action attribute provides the context of a button. It is typically used on a button element or element with role="button".

Note

The attribute in this section, "action", is one of three attributes named "action", "destination" and "purpose" for which we considered some alternatives. You can find a detailed discussion of the three attributes and alternatives at Review of approaches for Action, Destination, and Purpose.

The following is an example using the action attribute.

Example 1: Action Using data-action

<button data-action="undo">Revert</button>

A personalization agent may add a symbol, replace the text (button label) with a more familiar term, or give it a specific presentation.

Note that this attribute can only take a single token value, and there is no default value.

Characteristic	Value
Related Concepts:	link types [HTML52] and HTML types [HTML5]
Used in Roles:	All elements of the base markup
Inherits into Roles:	Placeholder
Value:	token

The following is the proposed token values used with action for buttons. Note that the following items represent an option or control that allows you to perform the action. They do not represent page regions.

Value	Description
add	Add the selected item or the item at the current location to a list.
brightness	Adjust the screen or application brightness. Often used with increase or decrease but is sometimes used alone as a menu name or item. Editor's note At risk pending implementations.
buy	Buy the selected item or buy the item at the current location. Often involves adding the current item into a shopping cart. (Implied simplification = "critical".)
cancel	Closes the dialog and discards any changes the user may have made within that dialog. (Implied simplification = "critical", the reason being if there is no [escape] option [cancel] must be present to abort the operation.)
captions	Show the settings for captions and subtitles.
channel	Adjust the channel of a multimedia component. Often used with increase or decrease but is sometimes used alone as a menu name or item. Editor's note At risk pending implementations.
checkout	Proceed to the purchasing process. (Implied simplification = "critical".)
close	Close the current dialog. (Implied simplification = "critical".)
color	Opens a color picker.
compose	Compose a new item such as an email. (Implied simplification = "critical".)
confirm	Confirms submission of the form request to the server. For example, an "ok" button. (Implied simplification = "critical".)
connect	Connect to a communication channel, such as an FTP server or Voice over IP channel. Often used with [aria-pressed = "true"] for on or [aria-pressed = "false"] for off.
copy	Copies the selected control, item or text and places it onto the clipboard.
cut	Removes the selected control, item or text and places it onto the clipboard.
date	Opens a date control. (Implied simplification= "critical".)
decrease	Decreases the level of the relevant setting. (Implied simplification= "critical".)
delete	Delete the current item, selected control, or text.
down	Changes the location of the selected item(s) downward.
download	Download a file from the server.
drag	Enables drag and drop capabilities. Often used with [aria-pressed = "true"] for on or [aria-pressed = "false"] for off.
edit	Edit the item or selection at the current location.
end	Moves to the terminus of a range, list, or sequence. This is typically used in a sequence of steps.
escape	Typically used to abort, cancel or change what is currently being displayed on the screen. A common application of the the esc key is to leave full screen mode. (Implied simplification = "critical", the reason being if there is no [cancel] option [escape] must be present to abort the operation)
expand	Expand or collapse the current item.
forward	Forward the current item such as an email.
opens-in-page-help	Opens a help function on the same page. (Implied simplification= "critical".)
increase	Increases the level of the relevant setting. (Implied simplification= "critical".)
label	Add a label to the selected item or the item at the current location.
language	Ability to select the preferred language for the content.
left	Changes the location of the selected item(s) to the left based on physical positioning. Note that the logical implication may depend on the direction of the page. If the logic is important, use next or previous.
loop	Plays the flow, presentation or a movie over and over again, once or without stopping. Often used with [aria-pressed = "true"] for on or [aria-pressed = "false"] for off. Editor's note At risk pending implementations.
media-position	Adjust the current playback position in the current media. Editor's note At risk pending implementations.
mode	Change the mode or functionality. (Implied simplification= "critical".)
more	Show more information.
move	Changes the position of a selected item(s). Often used with left, right, begin, end, increase (up) or decrease (down).
mute	Mute or toggle the mute option.
new	Open a new item. (Implied simplification= "critical".)
next	Go to the next item in the series. (Implied simplification = "critical".)
open	Open an item. (Implied simplification = "critical".)
order	Changes the position of the selected item within a list of items, while each item in the list has a layer position. Often used with increase (forward), decrease (back), first and end.
paste	Paste the content from the clipboard to the current position.
pause	Pause a multimedia, audio or video element or object. (Implied simplification = "critical".)
play	Play a multimedia, audio or video element or object. (Implied simplification = "critical".)
previous	Go to the previous item in the series. (Implied simplification = "critical".)
print	Print the current page, selection or the item at the current location.
profile	Opens the user's profile page.
properties	Shows the properties of an item.
received	Open the received folder.
refresh	Manually refresh the current contents of the screen.
remove	Removes an item from a list.
reply	Reply to the current item such as an email. (Implied simplification = "critical".)
reset	Resets all the controls to their initial or default values.
resize	Increase or decrease the font size. Often used with increase or decrease.
right	Changes the location of the selected item(s) to the right based on physical positioning. Note that the logical implication may depend on the reading direction of the page. If this logic is important, use next or previous instead.
save	Save the current content. (Implied simplification = "critical".)
scroll	Advances the view. Often used with left, right, begin, end, increase (up) or decrease (down).
send	Send a form, email or request. (Implied simplification = "critical".)
sent	Open the sent folder.
settings	Open settings and options.
skip	Skips the current step. This is typically used in a sequence of steps.
start	Moves to the beginning of a range, list, or sequence. This is typically used in a sequence of steps.
submit	Submits the form data or a request to the server. (Implied simplification = "critical".)
temperature	Adjust the temperature. Often used with increase or decrease but is sometimes used alone as a menu name or item. Editor's note At risk pending implementations.
toc	Resolves to a table of contents.
undo	Revert to the prior state before the user's most recent changes.
up	Changes the location of the selected item(s) upward.
upload	Upload a file to the server.
voice-commands	Activate or deactivate voice commands. Often used with `[aria-pressed = "true"]` for on or `[aria-pressed = "false"]` for off.
volume	Adjust the volume of a multimedia component. Often used with increase or decrease but is sometimes used alone as a menu name or item. Editor's note At risk pending implementations.

The destination attribute categorizes the target of a hyperlink.

A personalization agent or user agent may add additional familiar user interface features to help users understand the link and follow the right one easily. User agents might add a familiar customized icon to the link, style the link in a customized way, or position the link on the page in a location that the user generally expects to find a link of the particular type.

Note

The attribute in this section, "destination", is one of three attributes named "action", "destination" and "purpose" for which we considered some alternatives. You can find a detailed discussion of the three attributes and alternatives at Review of approaches for Action, Destination, and Purpose.

The following is an example using the destination attribute.

Example 2: Destination Using data-destination

<a href="home.html" data-destination="home">our main page</a>

See the destination sample user experience.

Note that this attribute can only take a single token value, and there is no default value.

Characteristic	Value
Related Concepts:	link types [HTML52] and HTML 5.2 autocomplete [HTML52]
Used in Roles:	All elements of the base markup
Inherits into Roles:	Placeholder
Value:	token

Value	Description
about	Information about the content owner or producer.
accessibility-statement	Information about the accessibility features in a web site or web content.
begin	Changes the location to the beginning item from a list of items or redirects the functionality to the first step in a sequence.
chat	Human help or a dialog help function such as a chat bot.
contact	Opens contact information for the content owner or producer.
email-recipient	Email address for the content owner or producer.
end	Changes the location to the end item from a list of items or redirects the functionality to the last step in a sequence.
feedback	Submit feedback or comment on the current item.
help	A help function that navigates to support or instructions.
home	Initial or main page of a website or application.
phone	Phone number for the content owner or producer.
post	Post current item. Item will be visible to other parties.
products	Products available from the content provider.
related	Adds a related item(s) to a pre-selected list of items.
services	Services available from the content provider.
signin	Sign in to the current web site or application.
signout	Sign out of the current web site or application.
sitemap	Content containing a list of all the pages in a web site.
social	Content provider on a social media platform. Note: the specific name of the social media platform should be included in the accessible name. Editor's note At risk pending implementations.
terms	The conditions or terms-of-use applicable to the website or web content.
tools	Available tools for interacting with the current content.

The purpose attribute provides the context of a text input field such as a text box. It is typically used on an input of type text, or an element with a corresponding role.

A personalization agent may add a symbol, replace the text with a more familiar term, or give it a specific presentation. Note that there is no default value.

The user experience may include filling in the field (autocomplete) or adding an icon to augment the input label.

The purpose values that would typically be on form inputs should provide context for the user. For example tel would relate to the user's telephone number.

Note that there is no default value, and there can be more than one space-seperated value for a field.

Note

The attribute in this section, "purpose", is one of three attributes named "action", "destination" and "purpose" for which we considered some alternatives. You can find a detailed discussion of the three attributes and alternatives at Review of approaches for Action, Destination, and Purpose.

The following is an example using the purpose attribute on a text input collecting a telephone number.
Example 3: Field Using data-purpose
```
<input type="text" name="telnum" data-purpose="tel"/>
```
The following is an example using the purpose attribute on a textarea input collecting both Country and Postal-code information.
Example 4: Field Using data-purpose - space separated values
```
<textarea name="country_zip" data-purpose="country-name postal-code"/>
```

Characteristic	Value
Related Concepts:	link types [HTML52] and HTML types [HTML5]
Used in Roles:	All elements of the base markup
Inherits into Roles:	Placeholder
Value:	token

Where the same value exists in the WCAG 2.1[WCAG21] Input Purposes for User Interface Components values, this specification uses that definition. This specification includes additional values that go beyond just collecting information about the user as referenced in WCAG 2.1 Success Criterion 1.3.5 Identify Input Purpose

Value	Description
additional-name	Additional names (in some Western cultures, also known as middle names, forenames other than the first name).
additional-name-initial	Additional or middle name initial.
address-level1	The broadest administrative level in the address, i.e., the province within which the locality is found; for example, in the US, this would be the state; in Switzerland it would be the canton; in the UK, the post town.
address-level2	The second administrative level, in addresses with two or more administrative levels; in the countries with two administrative levels, this would typically be the city, town, village, or other locality within which the relevant street address is found.
address-level3	The third administrative level, in addresses with three or more administrative levels.
address-level4	The most fine-grained administrative level, in addresses with four administrative levels.
address-line1	Street address (one line per field, line 1)
address-line2	Street address (one line per field, line 2)
address-line3	Street address (one line per field, line 3)
answer	Answer to a section question.
area	Administrative area, state, province, or region.
bday	Birthday.
bday-day	Day component of birthday.
bday-month	Month component of birthday.
bday-year	Year component of birthday.
cc-csc	Security code for the payment instrument (also known as the card security code (CSC), card validation code (CVC), card verification value (CVV), signature panel code (SPC), credit card ID (CCID), etc).
cc-exp	Expiration date of the payment instrument.
cc-exp-month	Month component of the expiration date of the payment instrument.
cc-exp-year	Year component of the expiration date of the payment instrument.
cc-name	Full name as given on the payment instrument.
cc-number	Code identifying the payment instrument (e.g., the credit card number).
cc-type	Type of payment instrument.
cc-given-name	Given name as given on the payment instrument (in some Western cultures, also known as the first name).
cc-additional-name	Additional names given on the payment instrument (in some Western cultures, also known as middle names, forenames other than the first name).
cc-family-name	Family name given on the payment instrument (in some Western cultures, also known as the last name or surname.
comment	Form comment section. Typically, a free text field.
country	Country code.
country-name	Country name.
current-password	The current password for the account identified by the username field (e.g., when logging in).
date-end	Set the end time of an event. Note We may remove this or harmonize with other date time standards. Editor's note At risk pending implementations.
date-start	Set the start date or the date of an event. Note We may remove this or harmonize with other date time standards. Editor's note At risk pending implementations.
email	E-mail address.
family-name	Family name (in some Western cultures, also known as the last name or surname).
fax	Full fax number, including international country code.
fax-area-code	Area code.
fax-country-code	International country code.
fax-local	Local fax number: full number minus country and area codes.
fax-national	National fax number: full number minus international country code and area code.
given-name	Given name (in some Western cultures, also known as the first name).
honorific-prefix	Prefix or title (e.g. "Mr.", "Ms.", "Dr.", "Mlle").
honorific-suffix	Suffix (e.g. "Jr.", "B.Sc.", "MBASW", "II").
impp	URL representing an instant messaging protocol endpoint (for example, "aim:goim?screenname=example" or "xmpp:fred@example.net”).
language	Ability to select the preferred language for the content. Note The use of the language token does not mandate the use of BCP47 values: authors can request content as either a BCP47 value or a simple text string.
name	Full name.
new-password	A new password (e.g., when creating an account or changing a password).
nickname	Nickname, screen name, handle: a typically short name used instead of the full name.
organization	Company name corresponding to the person, address, or contact information in the other fields associated with this field.
organization-title	Job title (e.g., "Software Engineer", "Senior Vice President", "Deputy Managing Director”).
photo	Photo or avatar.
postal-code	Postal code, post code, ZIP code, CEDEX code (if CEDEX, append "CEDEX", and the arrondissement, if relevant, to the address-level2 field).
sex	Gender identity (e.g., Female, Fa’afafine).
subject	Form subject. Typically, a free text field.
tel	Full telephone number, including country code.
tel-area-code	Area code component of the telephone number, with a country-internal prefix applied if applicable.
tel-country-code	Country code component of the telephone number.
tel-extension	Telephone number internal extension code.
tel-local	Telephone number without the country code and area code components.
tel-local-prefix	First part of the component of the telephone number that follows the area code, when that component is split into two components.
tel-local-suffix	Second part of the component of the telephone number that follows the area code, when that component is split into two components.
tel-national	Telephone number without the country code component, with a country-internal prefix applied if applicable.
time-end	Set the end time of an event. Note We may remove this or harmonize with other date time standards. Editor's note At risk pending implementations.
time-start	Set the start time or the time of an event. Note We may remove this or harmonize with other date time standards. Editor's note At risk pending implementations.
topic	Topic for the form. Typically, selected from a list of reserved words.
transaction-currency	The currency that the user would prefer the transaction to use.
transaction-amount	The amount that the user would like for the transaction (e.g. when entering a bid or sale price).
url	Home page or other Web page corresponding to the company, person, address, or contact information in the other fields associated with this field.
username	A username.

The simplification attribute differentiates between critical features and less important features for user interface simplification.

This allows simplified interfaces with less options or interfaces that emphasize critical features. Adaptations can be based on personalization settings.

Note that this attribute can only take a single token value, and there is no default value.

An example using the simplification attribute in the context of a submit button.
Example 5: Simplification Using data-simplification
```
<input value="Submit" type="submit" data-simplification="critical"/>
```
In this example, the simplification attribute is used on critical content — a newsletter from an elementary school. Important announcements about an early school dismissal is in a list of other activities. If this important information is missed, the parents might not be home in time, putting children at risk.
Example 6: Simplification Using data-simplification
```
<p>Years 2 - 3 are putting on a play next Tuesday. 
<strong data-simplification="critical">Therefore school will close at 1 pm on Tuesday</strong> 
 so we can get the school hall ready.</p>
```

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

Value	Description
`critical`	The `critical` setting should be used on: Controls and content that are essential for the key function (from the user perspective) of the page or application. Example: The send button for an email draft in an email application. Controls and content that are sometimes critical to use the site, such as "save my work" or "emergency instructions". Controls and content that are used by over 90% of a user group (such as parents or teachers) most times they interact with the content. Other controls or content that is critical to the page or application, at the author's discretion. (Authors are cautioned not to over-use this attribute value)
`medium` (default)	The `medium` setting should be used on: Controls and content that are used frequently but are not essential for the key functioning of the application. Example: The delete button for an email draft in an email application. Controls and content that are sometimes important for a user to interact with the site, such as settings to change colors or fonts. Controls and content that are used by over 60% of a user group (such as parents or teachers) when they interact with the content. Other controls or content, at the author's discretion.
`low`	The `low` setting should be used on: Controls and content that are rarely used or only used by advanced users. Example: The terms and services or the archive button for an email application.

The distraction attribute is intended to be used on non-essential distracting content, so that people who have problems keeping focus can minimize, re-order or turn the content off. An example user-experience would be to hide all non-essential distracting content.

Note that there is no default value.

Note that elements with the distraction attribute should also have a label or accessible name.

It has been noted that advertising constitutes the critical revenue stream for many content providers. The purpose of allowing users to hide (or systematically show and sequentially review) on-page advertising is simply to give distracted users the same control others have over such content. The user without a disability can ignore the advertisement and complete the task. The user who cannot ignore it, or TAB past it conveniently, is forced to grapple with a stumbling block that prevents them from completing a task.

Users will choose to look at advertising because it's informative. It's an important mechanism for learning about options in life. By allowing users to control when and how they see ads, they have the ability to avoid becoming frustrated by processes that prevent task completion. This allows them to see advertising as potentially useful information, not a source of frustration. The alternative is that a frustrated user will not follow up on the ad that caused the frustration.

Editor's note

The distraction attribute may appear to have some common features with the CSS prefers-reduced-motion media feature, however there are some significant differences:

the distraction attribute is applying semantics at the element level, whereas the CSS media feature is presentational and semantics-free.
the CSS prefers-reduced-motion media feature requires that the content author also provide an alternative experience for users who have the Reduced Motion option enabled - the distraction attribute does not.
the CSS prefers-reduced-motion media feature anticipates a reduced presentation, the distraction attributes anticipates that the content can be minimize, re-ordered or even turned off (hidden) from the end user.

Example using the distraction attribute in the context of an animated image.
Example 7: Distraction Using data-distraction
```
<img src="animated.gif" alt="animated banner advertising for Widgets" 
  data-distraction="sensory offer">
```
Example using the distraction attribute in the context of a stock ticker that starts and displays upon page load.
Example 8: Distraction Using data-distraction
```
<div data-distraction="sensory messages" class="stockticker-widget-container"></div>
```
Example using the distraction attribute in the context of a count-down timer that starts at the user’s request and updates in real-time the hours, minutes, and seconds until an event starts (or ends).
Example 9: Distraction Using data-distraction
```
<div data-distraction="sensory" class="countdown-widget-container"></div>
```
Example using the distraction attribute in the context of an audio clip that is played each time a step in a sequence of steps on a set of web pages is completed. Some users may find this sound distracting.
Example 10: Distraction Using data-distraction
```
<audio src="step-complete.mp3" data-distraction="sensory">
```
Example where haptic feedback is provided when items are added into a shopping cart. The user's device is fixed onto their wheelchair and the haptic feedback is distracting because it rattles the device within the mount. Implementation of this scenario may rely on the Notification API to implement the haptic feedback.

Characteristic	Value
Related Concepts:	SVG [SVG2] and DOM [DOM4] active
Used in Roles:	All elements of the base markup
Inherits into Roles:	Placeholder
Value:	token list

Value	Description
messages	Communication (auditory or visual) sent to or left for the user or the interface that allows interaction of text-based messages. Messages may also be automatically updating. Essential system messages should not be tagged as distractions. This includes but is not limited to WebRTC.
offer	An advertisement or offer for a product, feature, service, or content that is not essential to the user's current task.
overlay	Part of an application or content that is displayed over the top of other content in a secondary window or popup that blocks user interaction to the parent window. The content of the popup is not essential to the users task and was not intentionally initiated by the user.
sensory	Non-essential distracting content that includes movement, sound or other forms of sensory feedback. This includes: moving images (videos, animated GIFs, etc.); content that starts automatically or is automatically updating; and elements that change locations or generate audio feedback on the user's system.

The symbol attribute identifies the concept for symbols used in AAC devices, etc., for users who cannot process languages. The symbols are an alternative vocabulary, and multiple symbol sets exist today.

The symbol attribute accepts a numeric reference number.

A personalization agent can then augment or translate User Interfaces by:

converting text to symbols,
facilitating symbol-set translation: loading alternative, locally stored symbols that the user is familiar with, so they do not have to learn new symbols across different applications.

In some languages words and symbols are conjugated with sex or tense. In these cases more than one value maybe needed to map to a symbol. Authors should join values that map to a single conjugated word with a plus (+) sign (with no spaces between the values). See best practices for symbol values.

When there is more than one concept that is not part of a single conjugated term, multiple concepts can be referenced by separating them with white space. The order of multiple concepts should be the same as used in typical speech in the natural language of the content.

The reference numbers are the same references numbers used in Bliss (BCI numbers). Here is a link to the BCI numbers (PDF) and additional language translations (PDF) at the time of publication and the copyright licensing from Bliss. For additional updates after publication see our best practices for symbols page.

Editor's note

This specification is focused on allowing authors to make one-to-one mappings from parts of their content to concepts as defined by BCI. The rendering of the appropriate symbols for the user would be handled by the user agent, extension, or assistive technology. It is anticipated that symbol selection for rendering would take the form of a simple look-up.

Whilst this specification is not focused on rendering, here are some notes on the expected process, which may be of interest for authors and implementers.

The Bliss concept ID may map to one rendered symbol, or possibly more than one rendered symbol, in the user's chosen symbol set. This is because the user's chosen set may not have a single symbol to represent that one concept.
There would exist a mapping from Bliss concept ID to the user's chosen symbol set, which would allow a user agent to render the one (or more) symbols for that Bliss concept ID.
The mapping would ideally in future be provided along with a given symbol set, but it could be created by anyone.
Authors should not assume that one concept ID maps to one symbol—though authors should not need to make any assumptions about rendering, other than ensuring their content can be resized and will reflow, as per WCAG 2.1 Success Criteria 1.4.4 Resize Text and 1.4.10 Reflow.

Here are some examples using the symbol attribute.

Symbols for individual words.

Example 11: Symbols for individual words

<span data-symbol="13621">Cup</span> of <span data-symbol="17511">Tea</span>

Symbols used with an image (alt text represented as a symbol).
Example 12: Symbols used with an image
```
<img src="cup.png" data-symbol="13621" alt="Cup"/>
```
Symbols with conjugation. In this example a symbol is used for "her name" for the conjugated Hebrew word, שמה. The plus sign is used with no spaces 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).
Example 13: Symbols with conjugation
```
<img src="her-name.png" alt="שמה" data-symbol="15691+14707"/>
```

Characteristic	Value
Related Concepts:	microdata [microdata], SKOS Core Guide [swbp-skos-core-guide] and RDFa [rdfa-primer]
Used in Roles:	All elements of the base markup
Inherits into Roles:	Placeholder
Value:	URI

WAI-Adapt: Content Module

Abstract

Status of This Document

1. Introduction

1.1 Background

1.2 WAI-Adapt: Content Module

1.3 Vocabulary Structure and Implementations

1.3.1 Properties

1.3.2 Values

1.4 Use Cases and Requirements

2. Terms

3. Vocabulary

3.1 action

3.1.1 Description

3.1.2 Example

3.1.3 Characteristics

3.1.4 Values

3.2 destination

3.2.1 Description

3.2.2 Example

3.2.3 Characteristics

3.2.4 Values

3.3 purpose

3.3.1 Description

3.3.2 Example

3.3.3 Characteristics

3.3.4 Values

3.4 simplification

3.4.1 Description

3.4.2 Examples

3.4.3 Characteristics

3.4.4 Values

3.5 distraction

3.5.1 Description

3.5.2 Examples

3.5.3 Characteristics

3.5.4 Values

3.6 symbol

3.6.1 Description

3.6.2 Examples

3.6.3 Characteristics

4. Privacy and Security Considerations

A. Acknowledgments

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

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

A.3 Enabling funders

B. References

B.1 Informative references