Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
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:
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 Personalization Semantics Content Module 1.0 is a component of the Personalization Semantics series introduced in the Personalization Semantics Explainer 1.0 document [personalization-semantics-1.0].
This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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 a Working Draft. This document is intended to become a W3C Recommendation.
This is a Working Draft of Personalization Semantics Content by the Accessible Platform Architectures Working Group. Personalization Semantics Content Module is a part of Personalization Semantics, which is introduced in the Personalization Semantics Explainer 1.0. This version updates values of semantics and fixes editorial issues.
To comment, file an issue in the W3C personalization semantics GitHub repository. If this is not feasible, send email to public-personalization-tf@w3.org (archives). Comments are requested by 10 September 2021. In-progress updates to the document may be viewed in the publicly visible editors' draft.
Publication as a Working Draft does not imply endorsement by the W3C Membership.
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 15 September 2020 W3C Process Document.
This section is non-normative.
This specification module enables authors to add semantic information about content at the element level, in order to facilitate a more familiar or comprehensible interface for the individual user. Multiple screen renderings (transformations) are supported in order to meet the differing needs of different users. Final renderings — generated via helper apps or 3rd-party tools — are ultimately defined by the user's configuration settings.
The goal of the attributes and values described in this specification is to enable personalized communication and web content interaction for the individual user. This specification includes facilities to:
Personalization Semantics is a series of technical specifications that provide the element-level attributes and values which enable user agents and helper-applications to adapt content to an individual user's needs. It relies on author-supplied page and element level metadata in order to achieve individualized personalization.
Personalization Semantics currently consists of three modules: Content, Help and Support, and Personalization Tools. The specification defined in this document is the Personalization Semantics Content Module—the first of the Personalization Semantics Modules series.
Personalization Semantics is more fully introduced in our Personalization Semantics Explainer [personalization-semantics-1.0].
Personalization Semantics Content Module is the first part of the Personalization Semantics technical specification, which provides personalization 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 Content Module enhances web content by providing additional information about form controls, buttons, links, and other user interface elements. User agents use these semantics to augment or adapt content to the user’s scenario — for example allowing for the conversion of text to symbols. This helps users with varying needs to understand the content by providing support for simplification and/or a way to manage unnecessary distractions.
All the vocabulary in Personalization Semantics Content Module is constructed of properties and their values. Please see our Personalization Semantics Explainer.
The vocabulary implementations included in this document are available at our implementations wiki page.
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.
The Requirements for Personalization Semantics describes use cases and requirements. This module provides properties to fulfill those requirements related to adapting content.
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.
The action
attribute provides the context of a button. It is typically used on a button element or element with role="button".
The following is an example using the action
attribute.
<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 dirction 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 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.
The following is an example using the destination
attribute.
<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.
purpose
attribute on a text input collecting a telephone number.
<input type="text" name="telnum" data-purpose="tel"/>
purpose
attribute on a textare input collecting both Country and Postal-code information.
<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. |
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 county 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.
simplification
attribute in the context of a submit button.
<input value="Submit" type="submit" data-simplification="critical"/>
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.
<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:
|
medium (default) |
The medium setting should be used on:
|
low |
The low setting should be used on:
|
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.
distraction
attribute in the context of an animated image.
<img src="animated.gif" alt="animated banner advertising for Widgets"
data-distraction="sensory offer">
distraction
attribute in the context of a stock ticker that starts and displays upon page load.
<div data-distraction="sensory messages" class="stockticker-widget-container"></div>
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).
<div data-distraction="sensory" class="countdown-widget-container"></div>
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.
<audio src="step-complete.mp3" data-distraction="sensory">
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:
In some languages words and symbols are conjugated with sex or tense. In these case more then one value maybe needed to map to a symbol. Authors should join values that map to a single conjugated word with a \ + \ sign with a space on each side of the \ + \ sign. (User agent may choose to accept values for a conjugated term that have been separated without the spaces.) 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.
Here are some examples using the symbol
attribute.
<span data-symbol="13621">Cup</span> <span data-symbol="12324">of</span>
<span data-symbol="17511" >Tea</span>
<span data-symbol="13621 12324 17511">cup of Tea</span>
<img src="cuptea.png" data-symbol="13621 12324 17511" alt="cup of Tea"/>
<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 |
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 setting are recommended to follow best practices to keep user information secure.
The Privacy and Security Considerations of Personalization Semantics Content Module is also discussed at issue #131.
This section is non-normative.
The following people contributed to the development of this document.
This publication has been funded in part with U.S. Federal funds from the Health and Human Services, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR) under contract number HHSP23301500054C. 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.