THIS DOCUMENT IS OBSOLETE. Please see AOM API instead.

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an example. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

Please see AOM API instead.

Things we want feedback on!

Accessibility API

The API provides bunch of interfaces that are used to express the semantics of web content in a way that assistive technologies (AT) knows how to deal with. Also it provides the ability to search and traverse the content and interact with it. It has a way to extend existing semantics of the markup, and add new semantics for inaccessible content like drawings made using the canvas element. Each piece of semantic content has an associated accessible element the AT operates on.

Terms

An assistive technology or AT is software that provides an improved user experience for different types of users including people with disabilities. It can be in the form of a native application, or web application (e.g., zoom tool), or service (e.g., speech-to-text).

A content entity is semantically isolated piece of content. For example, interactive content in [[!HTML]].

An accessible element is an object expressing the semantics of a content entity. Such objects are represented by the AccessibleElement interface.

A role of an accessible element identifies the function of the accessible element to assistive technology (e.g., "button", "textbox", etc. See also [[!WAI-ARIA]] roles).

A name of an accessible element is a primary human readable property of an accessible element. For example, assistive technology could present the name of the accessible element to the user.

A description of an accessible element is a secondary human readable property of an accessible element. It's used to provide more detailed information than name to the user about a content entity the accessible element was created for (e.g., a tool tip).

A text of an accessible element is text associated with the accessible element.

An accessible element has a set of states, which is represented by a Set-like object. Conceptually, each one of these states is a boolean that represents the state the content entity is currently in. For example, if a [[!HTML]] button element is in the focused state (e.g., the user has focused the button by tabbing to it), then its accessible element will have "focused" state in its accessible states.

An attribute of an accessible element is a property that provides extra information about its content entity. For example, autocomplete feature on an input element would map to autocomplete attribute with possible values inline, list, or both.

A pattern of an accessible element expresses the associated semantics of the content entity that is not expressed by means of the AccessibleElement interface.

A accessible element can have one or more relations to other accessible elements. Each relation has a relation type that expresses its semantics. Relations of an accessible objects are represented by objects that implement the Set interface.

An user action of an accessible element is an action supported by the content entity. An user action can be performed on a content entity by the user or the user agent via script (e.g., a button click). In the API, user actions are represented by objects that implement the Set interface.

A device-dependent interaction includes things like keyboard shortcut or mouse gesture used to invoke the action. In the API, a device-dependent interaction is represented by the Interaction interface. All supported device-dependent interactions on an accessible element are represented by objects that implement the InteractionMap interface.

An accessible tree is a tree of accessible elements associated to each other by a parent-child relationship.

An accessible parent of the referred accessible element is its parent in the accessible tree.

An accessible child of the referred accessible element are its child accessible elements in the accessible tree. It is represented by the AccessibleChildren interface.

An accessible DOM node or accessible DOM element is a [[!DOM]] Node or Element that has an associated accessible element.

An accessible position is a point in the content when it's presented in one-dimensional way, that can be semantically traversed. For example, paragraph text can be traversed by words, or traversing the document using HTML's outlining algorithm. User focus can also be described by an accessible position; for example tabbing from one HTML input element to another within a form.

An accessible pin is an object representing an accessible position and implementing AccessiblePin interface.

Understanding the terms

Each content entity has an associated accessible element. Each accessible element is described by accessible properties like role, name, relations etc.

accessible properties diagram
Accessible properties.

Accessible elements can be related to each other by number of different types.

accessible relations diagram
Relations. A color of arrows connecting accessible element represent own relation type.

All accessible elements are organized into accessible trees. In other words, all accessible elements are supposed to stay in parent-child relationship. The assistive technology can traverse the document by traversing its accessible tree.

accessible tree
Accessible tree.

The browser exposes semantics of the content to the assistive technology like screen readers or screen magnifiers softwares via platform APIs like ATK, IAccessible2, UIA, NSAccessibility or this API. The assistive technology communicates back to the content by the browser via platform APIs.

overview diagram
Overview of the communication between the content and the assistive technology.

Extensions to the Node interface

Assistive technology, or the developer, can request an accessible element from a [[!DOM]] Node if the Node is accessible, i.e. it expresses semantics to the assistive technology. 

partial interface Node {
  readonly attribute AccessibleElement? a11ement;
};

AccessibleElement attribute

The AccessibleElement attribute return the accessible element associated with this Node (if any). Otherwise, it returns null.

AccessibleElement interface 

interface AccessibleElement {
  attribute DOMString role;
  attribute DOMString name;
  attribute DOMString description;
  attribute DOMString text;

  readonly attribute AccessibleIterable states;
  readonly attribute AccessibleIterable attributes;
  readonly attribute AccessibleIterable patterns;
  readonly attribute AccessibleIterable relations;

  boolean is(DOMString ... something);
  any get(DOMString attribute);
  boolean has(DOMString attribute);
  object to(DOMString pattern);

  AccessibleElement? relativeOf(DOMString type);
  sequence<AccessibleElement> relativeOfAll(DOMString type);

  readonly attribute Actions actions;
  void activate(DOMString action);
  Interactions interactionsOf(optional DOMString action, optional DOMString device);

  readonly attribute AccessibleElement? parent;
  readonly attribute AccessibleChildren children;

  readonly attribute Node? DOMNode;
  attribute AccessibleSource? source;
};

role attribute

The role attribute represents the accessible role that is either developer defined or a role as per [[!WAI-ARIA]] (e.g., "button", "menu", "textfield").

For the author convenience the attribute value may be a space separated list of roles. This is useful when an accessible element should express semantics of both roles but the taxonomy misses a separate role for that. For example, a check menu item accessible element may have menuitem checkbox role if the role taxonomy doesn't have checkmenuitem role. In this case is method is supposed to return true for both checkbox and menuitem values.

name attribute

The name attribute represents name.

When setting, ...

description attribute

The description attribute description

When setting, ...

text attribute

The text attribute represents text.

When setting, ...

states attribute

The states attribute represents the states.

Returns an iterable for all states exposed on the accessible element. The implementation is not required to pre-compute any of the states.

attributes attribute

The attributes attribute represents attributes.

The accessible element can support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

Returns an iterable for all object attributes exposed on the accessible element. The implementation is not required to pre-compute any of the attributes.

Set of exposed attributes depends on semantics of the [[!DOM]] element. As an example, typical attributes are:

DOMString autocomplete:
Exposed on text fields. Values are list, none, inline, both.
DOMString live:
Points that the accessible is live region. Values are assertive and polite.
DOMString relevant:
Lists all notifications that qualifies for live region.

patterns attribute

The patterns attribute represents the patterns.

Returns an iterable for all patterns exposed on the accessible element. The implementation is not required to pre-compute any of the values.

Each markup can come with own set of supported patterns. A single accessible element may support several patterns. A typical example of a pattern is table cell pattern which has extra properties like row index and column index.

relations attribute

The relations attribute represents the relation types on the accessible element.

Returns an iterable for all relation types that the accessible element has. The implementation is not required to pre-compute any of the relations.

is method

Return true if the accessible element complies with the given values. A state, role or pattern can be used as a value. In case of states the method returns true if the accessible element has the given state. In case of role the method returns true if the accessible element role belongs to a role taxonomy of the given role value. In case of pattern value the method returns true if the accessible element supports the given pattern.

The taxonomy provider must make sure that role and states taxonomies don't overlap in names. If a markup have a pattern and a role of same name then each accessible element having the role in its role taxonomy must implement a pattern of same naming. For example, HTML table cell has cell role and exposes cell pattern.

In the example is method calls on a HTML button return true. 

let al = document.getElementById("button").a11ement;
console.assert(al.is("widget", "focusable"), "should a focusable widget");

get method

Return a value of the request attribute on this accessible element.

has method

Return true if the given attribute is present on the accessible element.

The method can be used to check whether the accessible element has non empty text properties like name, description or text.

to method

Return an object representing the requested pattern if exposed by the accessible element. Otherwise returns null.

The implementation is allowed to return same object or a new one.

The implementation is allowed to expose predefined set of patterns right on an accessible element object by default.

The example of queries cell pattern on a HTML td element and logs its row and column indexes. 

var al = document.getElementById("td").a11ement;
if (al.is("cell")) {
  let cell = al.to("cell");
  console.log(cell.rowindex);
  console.log(cell.colindex);
}

relativeOf method

Returns a relative accessible element of the given relation type for this accessible element if any. If the accessible element has multiple relatives then the first one is returned.

relativeOfAll method

Returns all relative accessible elements of the given relation type for this accessible element. If there are no relatives then empty sequence is returned.

actions attribute

Returns a set of all actions exposed by the accessible element. Returned object implements Actions interface.

An accessible element may expose number of actions, for example, a tree item accessible typically has two actions: activate, which makes the tree item focused, and expand / collapse action, which expands or collapses its subtree.
Here's a demo list of possible actions:
activate
Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, jump on links, press on buttons, check and uncheck on checkboxes. Accessible element may provide more than one action. For example, tree item can provide select / unselect as its primary action and expand / collapse as secondary. Tree column may implement sort action.
focus
Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
scroll
Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to. Extra parameter: delta of ScrollDelta.
drag and drop
Used to start dragging and dropping the content related to the accessible element the action is invoked on.
zoom
Zooms the content corresponding the accessible the action is invoked on. Extra parameters: ratio of unsigned double. Values greater than 1 zoom in the area, values lesser than 1 zoom out it. 1 brings the area to its normal size.
undo and redo
Performs clipboard operations on the accessible element of the editable content.

activate method

Invokes the given action on the accessible element.

The method may take extra information to invoke an action. For example, zoom action may take a zoom ratio as a parameter to change the zoom.

The example below zooms the document by ratio of 2 and then back to normal. 

var al = document.a11ement;
al.activate("zoom", 2);
al.activate("zoom", 1);

The second example scrolls the page to (400, 100) point and then scrolls it 2 pages down. 

al.activate("scroll", { x: 400, y: 100 });
al.activate("scroll", { mode: "page", count: 2 });

interactionsOf method

Returns a list of all interactions for given action and device if provided. Returned object implements Interactions interface.

parent attribute

The parent attribute represents accessible parent of this accessible element.

children attribute

The children attribute represents the child accessible elements of this accessible element.

Returns AccessibleChildren object containing all child accessible elements.

DOMNode attribute

Returns a DOM node associated with this accessible element if any.

Patterns

The section lists general propose patterns, that can be exposed by elements from any markup.

AccessibleItem

The AccessibleItem interface is exposed by accessible elements that represent an article in an enumeration, like a list, combobox, tree or grid widgets. 

interface AccessibleItem {
  readonly attribute AccessibleElement? widget;
  readonly attribute unsigned long index;
  readonly attribute unsigned long size;
  readonly attribute unsigned long level;
};

widget attribute

Returns an accessible element for a widget associated with this item. For example, it returns an HTML select accessible element for HTML option, and HTML table accessible for its HTML td element.

index attribute

Returns an index of the item within its group.

size attribute

Returns the amount of items of the group this item belongs to.

level attribute

Returns the level of the item if applicable. For example, it returns a nesting level in case of tree items.

AccessibleCell interface

The AccessibleCell interface is exposed by accessible elements created for cell-like elements. For example, cells of table, grid or tree table widgets. 

interface AccessibleCell {
  readonly attribute unsigned long rowIndex;
  readonly attribute unsigned long colIndex;
  readonly attribute unsigned long rowSpan;
  readonly attribute unsigned long colSpan;
};

rowIndex attribute

Returns a row index of the cell within the table.

colIndex attribute

Returns a column index of the cell within the table.

rowSpan attribute

Returns a rows number the cell is spanned to.

colSpan attribute

Returns a columns number the cell is spanned to.

AccessibleValue interface

The AccessibleValue interface is exposed by accessible elements having numerical value. Examples are slider or meter widgets. 

interface AccessibleValue {
  readonly attribute double max;
  readonly attribute double min;
  readonly attribute double low;
  readonly attribute double high;
  readonly attribute double optimum;
  readonly attribute double step;
  readonly attribute double value;
};

max attribute

Returns an upper bound of a range.

min attribute

Returns a lower bound of a range.

low attribute

Returns a high limit of a low range.

high attribute

Returns a low limit of a high range.

optimum attribute

Returns an optimum value in gauge.

step attribute

Returns a minimal possible increment of value.

step attribute

Returns a current value of the widget.

AccessiblePin interface

AccessiblePin serves to traverse the content, for example, if you need to navigate a document by headings or navigate a paragraph by words. It describes an accessible position in the content. The accessible pin can be moved into the given direction within the document to the content complying with the given criteria. A movement can be illustrated by verbal descriptions like "move the pin forward to a next heading" or "move the pin one word back". 

[Constructor(AccessibleElement anchor, optional AccessibleElement root)]
interface AccessiblePin {
  AccessiblePin? set(AccessibleElement anchor, Offset offset);
  AccessiblePin? move(Where where, optional Criteria criteria);

  readonly attribute AccessibleElement root;
  readonly attribute AccessibleElement? anchor;
  readonly attribute Offset;
};

enum Where {
  "forward",
  "backward"
};

enum Offset {
  "before",
  "at",
  "after"
};

callback Criteria = boolean (AccessibleElement);

set method

Sets the accessible pin to the given accessible and offset.

Returns a reference to itself if succeeded. Otherwise returns null.

move method

Moves the accessible pin to a next/previous position in the accessible tree according to the criteria. If the criteria is omitted then it moves the pin to a next/previous accessible element in the accessible tree.

Returns a reference to itself if succeeded. Otherwise returns null.

root attribute

Returns the accessible pin's anchor accessible element.

anchor attribute

Returns the accessible pin's anchor accessible element.

offset attribute

Returns the accessible pin's offset relative its anchor accessible element.

Where constants

forward is used to move an accessible pin forward in an accessible tree it resides in.

backward is used to move an accessible pin backward in an accessible tree it resides in.

Offset constants

before is used to set an accessible pin right before its anchor.

at is used to set an accessible pin at the anchor. For example, if the pin follows the focus, and a button is focused then the pin is at the button.

after is used to set an accessible pin right after its anchor.

Criteria function

criteria is a function defines rules that describe how accessible pin should be moved within an accessible tree.

Set interface

an object to list values of a given accessible property of an accessible element, for example, states, attributes or patterns. Implementation is not required to compute any value until requested. 

[NoInterfaceObject]
interface AccessibleIterable {
  readonly iterable<DOMString>;
};

Example of usage

Example of a script that logs to console all accessible element states. 

let al = document.getElementById("foo").a11ement;
for (let state of al.states) {
  console.log(state);
}

Actions interface

a set-like object listing all actions exposed by the accessible element. Implementation is not required to compute any value until requested. 

interface Actions {
  readonly setlike<Action>;
};

Action interface

an object representing an action on an accessible element.

name attribute

The action name.

description attribute

A localized description of the action. 

interface Action {
  stringifier readonly attribute DOMString name;
  readonly attribute DOMString description;
};

Example of usage

An example of a script logging all available actions on the accessible element. 

        var set = accElm.actions;
if (set.size() == 0) {
  console.log("no actions on accessible element");
} else {
  console.log("accessible element has " + set.size() + " actions");
  set.forEach(action => say(action.description));
}

Interactions interface

a set-like object listing all interactions exposed by the accessible element. Implementation is not required to compute any value until requested. 

interface Interactions {
  readonly setlike<Interaction>;
  boolean hasAnyOf(DOMString ... interaction);
};

hasAnyOf method

Returns true if any of the given interaction codes is supported on the accessible element.

Interaction interface

An object representing an interaction used to invoke an action on an accessible element. 

interface Interaction {
stringifier readonly attribute DOMString code;
readonly attribute DOMString device;
readonly attribute DOMString type;
};

code attribute

A string representation of the interaction.

An example of code value is shift + alt + A for accesskey, or swipe geasture for touch device.

device attribute

A device the interaction is associated with.

type attribute

A string value revealing a nature of the interaction. For example, it can be used to give a hint to a screen reader whether the interaction is not standard one and should be announced to the user, or about any conditions that should be met to trigger it, i.e. whether interaction is global or a control has to have the focus.

Example of usage

An example of a script logging all available interactions for each action on the accessible element. 

var actions = al.actions;
actions.forEach(action => { var codes = al.interactionsOf(action);
                               console.log(action);
                               codes.forEach(c => console.log(c.description));
                          });

AccessibleChildren interface

The AccessibleChildren is an iterable interface aimed to work with child accessible elements. 

interface AccessibleChildren {
  iterable<AccessibleElement>;
};

Dependencies

The following definitions are in the [[!HTML]] specification:

Acknowledgements

Many thanks to Robin Berjon for making our lives so much easier with his cool tool.