Graphics Accessibility API Mappings

W3C Candidate Recommendation

This version:
Latest published version:
Latest editor's draft:
Implementation report:
Previous version:
(Igalia, S.L.)
(IBM Corporation) (until September 2016)
(Knowbility) (until August 2017)
(IBM Corporation)


The Graphics Accessibility API Mappings defines how user agents map the WAI-ARIA Graphics Module [GRAPHICS-ARIA-1.0] markup to platform accessibility APIs. It is intended for user agent developers responsible for accessibility in their user agent so that they can support the accessibility of graphics such as that created for [SVG] or [HTML52].

The implementation of this specification in user agents enables authors to produce more accessible graphics by conveying common graphics semantics to assistive technologies. It provides Accessibility API Mapping guidance for the roles defined in the WAI-ARIA Graphics Module [GRAPHICS-ARIA-1.0].

The Graphics Accessibility API Mappings is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

Status of This Document

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

This is a Candidate Recommendation of Graphics Accessibility API Mappings 1.0 by the Accessible Rich Internet Applications Working Group. This is a call for implementations; the Accessible Rich Internet Applications Working Group requests that implementations be submitted by 27 April 2018. The Working Group targets 27 April 2018 to complete the testing process and produce the implementation report. A history of changes to Graphics-AAM 1.1 is available in the appendix.

Graphics-AAM was previously published as a Candidate Recommendation on 29 March 2018. This is an editorial republication to restore ids on some elements which had been inadvertently removed and are needed as targets for dependent specifications. Because there are no substantive changes in this version, the comment due date and implementation report target date have not been extended.

Exit Criteria: The Accessible Rich Internet Applications Working Group intends to exit the Candidate Recommendation stage and submit this document for consideration as a W3C Proposed Recommendation after documenting implementation of each feature. For every platform with mappings in this specification, at least one implementation of 75% of the mappings to that platform will demonstrate implementability on that platform. Multiple implementations of each platform are not required because some platforms have only one implementation. For features that are not platform-specific, passing test results in at least two different implementations will be documented to demonstrate implementability.

Comments: The Accessible Rich Internet Applications Working Group primarily seeks feedback in relation to implementation of Graphics-AAM, but feedback on any aspect of the specification is accepted. When submitting feedback, please consider issues in the context of the companion documents. To comment, file an issue in the W3C ARIA GitHub repository. If this is not feasible, send email to (comment archive). Comments are requested by 27 April 2018. In-progress updates to the document may be viewed in the publicly visible editors' draft.

This document was published by the Accessible Rich Internet Applications Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 27 April 2018.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation 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 1 February 2018 W3C Process Document.

1. Introduction §

This section is non-normative.

The Graphics Accessibility API Mappings specification provides role mappings for the roles in the WAI-ARIA Graphics Module [GRAPHICS-ARIA-1.0].

For web documents and applications, the essential semantic information is encapsulated within the Document Object Model (DOM). Assistive technologies obtain this information from the user agent, which maps elements and attributes to the platform Accessibility API.

The original suite of element semantics defined by WAI-ARIA 1.0 only considered graphics as individual embedded images, with no interactivity or meaningful semantic structure. It was therefore not sufficient for communicating complex graphics, such as labelled diagrams or data charts, or for interactive graphics. The WAI-ARIA Graphics Module defines a core set of three roles that can convey the structure of a graphic. This specification defines how user agents should expose those roles to the accessibility APIs currently in use, so that the semantic information is available to assistive technologies that use those APIs.

For an introduction to WAI-ARIA, see the WAI-ARIA Overview. It is part of a set of resources that define and support the WAI-ARIA specification, including the following documents:

2. Conformance §

The main content of this specification is normative and defines requirements that impact conformance claims. Introductory material, appendices, sections marked as "non-normative" and their subsections, diagrams, examples, and notes are informative (non-normative). Non-normative material provides advisory information to help interpret the guidelines but does not create requirements that impact a conformance claim.

Normative sections provide requirements that user agents must follow for an implementation to conform to this specification. The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Keywords for use in RFCs to indicate requirement levels [RFC2119]. RFC-2119 keywords are formatted in uppercase and contained in an element with class="rfc2119". When the keywords shown above are used, but do not share this format, they do not convey formal information in the RFC 2119 sense, and are merely explanatory, i.e., informative. As much as possible, such usages are avoided in this specification.

Normative sections provide requirements that authors, user agents and assistive technologies MUST follow for an implementation to conform to this specification.

Non-normative (informative) sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.

3. Important Terms §

While some terms are defined in place, the following definitions are used throughout this document.

Accessibility API

Operating systems and other platforms provide a set of interfaces that expose information about objects and events to assistive technologies. Assistive technologies use these interfaces to get information about and interact with those widgets. Examples of accessibility APIs are Microsoft Active Accessibility [MSAA], Microsoft User Interface Automation [UI-AUTOMATION], MSAA with UIA Express [UIA-EXPRESS], the Mac OS X Accessibility Protocol [AXAPI], the Linux/Unix Accessibility Toolkit [ATK] and Assistive Technology Service Provider Interface [AT-SPI], and IAccessible2 [IAccessible2].

Assistive Technologies

Hardware and/or software that:

  • relies on services provided by a user agent to retrieve and render Web content
  • works with a user agent or web content itself through the use of APIs, and
  • provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities

This definition may differ from that used in other documents.

Examples of assistive technologies that are important in the context of this document include the following:

  • screen magnifiers, which are used to enlarge and improve the visual readability of rendered text and images;
  • screen readers, which are most-often used to convey information through synthesized speech or a refreshable Braille display;
  • text-to-speech software, which is used to convert text into synthetic speech;
  • speech recognition software, which is used to allow spoken control and dictation;
  • alternate input technologies (including head pointers, on-screen keyboards, single switches, and sip/puff devices), which are used to simulate the keyboard;
  • alternate pointing devices, which are used to simulate mouse pointing and clicking.

In this specification, attribute is used as it is in markup languages. Attributes are structural features added to elements to provide information about the states and properties of the object represented by the element.


A set of instance objects that share similar characteristics.


In this specification, element is used as it is in markup languages. Elements are the structural elements in markup language that contains the data profile for objects.


A programmatic message used to communicate discrete changes in the state of an object to other objects in a computational system. User input to a web page is commonly mediated through abstract events that describe the interaction and can provide notice of changes to the state of a document object. In some programming languages, events are more commonly known as notifications.


Content provided for information purposes and not required for conformance. Content required for conformance is referred to as normative.


Required for conformance. By contrast, content identified as informative or "non-normative" is not required for conformance.


In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or more elements, and rendered by user agents.

In the context of programming, the instantiation of one or more classes and interfaces which define the general characteristics of similar objects. An object in an accessibility API may represent one or more DOM objects. Accessibility APIs have defined interfaces that are distinct from DOM interfaces.

Attributes that are essential to the nature of a given object, or that represent a data value associated with the object. A change of a property may significantly impact the meaning or presentation of an object. Certain properties (for example, aria-multiline) are less likely to change than states, but note that the frequency of change difference is not a rule. A few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often. See clarification of states versus properties.


Main indicator of type. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.


The meaning of something as understood by a human, defined in a way that computers can process a representation of an object, such as elements and attributes, and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.


A state is a dynamic property expressing characteristics of an object that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities. See clarification of states versus properties.

User Agent

Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.


Discrete user interface object with which the user can interact. Widgets range from simple objects that have one value or operation (e.g., check boxes and menu items), to complex objects that contain many managed sub-objects (e.g., trees and grids).

4. Mapping WAI-ARIA to Accessibility APIs §

4.1 General rules for exposing WAI-ARIA semantics §

This section MUST conform to General rules for exposing WAI-ARIA semantics in [CORE-AAM-1.1].

5. Conflicts between native markup semantics and WAI-ARIA §

User agents MUST conform to Conflicts between native markup semantics and WAI-ARIA in [CORE-AAM-1.1].

6. Exposing attributes that do not directly map to accessibility API properties §

User agents MUST conform to Exposing attributes that do not directly map to accessibility API properties in [CORE-AAM-1.1].

7. Role mapping §

Platform accessibility APIs traditionally have had a finite set of predefined roles that are expected by assistive technologies on that platform and only one or two roles may be exposed. In contrast, WAI-ARIA allows multiple roles to be specified as an ordered set of space-separated valid role tokens. The additional roles are fallback roles similar to the concept of specifying multiple fonts in case the first choice font type is not supported.

7.1 General Rules §

User agents MUST conform to the Role Mapping General Rules accessibility API computational requirements in [CORE-AAM-1.1].

7.2 Role Mapping Table §

This section defines how roles in graphics map to platform accessibility APIs based on their native host language semantics and when WAI-ARIA roles are applied. This section refers directly to the Core Accessibility API Mappings specification.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
WAI-ARIA Role MSAA + IAccessible2 Role + Other IAccessible2 Features UIA Control Type + Other Features ATK/AT-SPI Role AXAPI


IAccessible2: Object attribute xml-roles:graphics-document.

Control Type: 'Document'.

Expose ROLE_DOCUMENT_FRAME and object attribute xml-roles:graphics-document.

AXRole: AXGroup
AXSubrole: AXDocument
AXRoleDescription: 'document'
graphics-object ROLE_SYSTEM_GROUPING +

IAccessible2: Object attribute xml-roles:graphics-object.

Control Type: 'Group'.

Expose ROLE_PANEL and object attribute xml-roles:graphics-object.

AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
graphics-symbol ROLE_SYSTEM_GRAPHIC

IAccessible2: Object attribute xml-roles:graphics-symbol.

Control Type: 'Image'.

Expose ROLE_IMAGE and object attribute xml-roles:graphics-symbol.

AXRole: AXImage
AXSubrole: <nil>
AXRoleDescription: 'image'

A. Change Log §

The full commit history to Graphics Accessibility API Mappings 1.0 is available.

A.1 Substantive changes since the First Public Working Draft §

B. Acknowledgments §

This section is non-normative.

The following people contributed to the development of this document.

B.1 Participants active in the SVG accessibility task force at the time of publication §

B.2 Participants active in the ARIA WG at the time of publication §

B.3 Enabling funders §

This publication has been funded in part with U.S. Federal funds from the Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR), initially under contract number ED-OSE-10-C-0067 and currently under contract number HHSP23301500054C. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

C. References §

C.1 Normative references §

Core Accessibility API Mappings 1.1. Joanmarie Diggs; Joseph Scheuhammer; Richard Schwerdtfeger; Michael Cooper; Andi Snow-Weaver; Aaron Leventhal. W3C. 14 December 2017. W3C Recommendation. URL:
WAI-ARIA Graphics Module. Amelia Bellamy-Royds; Joanmarie Diggs; Michael Cooper; Fred Esch; Richard Schwerdtfeger. W3C. 29 March 2018. W3C Candidate Recommendation. URL:
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:

C.2 Informative references §

Accessible Name and Description: Computation and API Mappings 1.1. Joseph Scheuhammer; James Craig; Andi Snow-Weaver; Aaron Leventhal. W3C. 17 March 2016. W3C Working Draft. URL:
Assistive Technology Service Provider Interface. The GNOME Project. URL:
ATK - Accessibility Toolkit. The GNOME Project. URL:
The NSAccessibility Protocol for macOS. Apple, Inc. URL:
HTML 5.2. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo; Sangwhan Moon. W3C. 14 December 2017. W3C Recommendation. URL:
IAccessible2. Linux Foundation. URL:
Microsoft Active Accessibility (MSAA) 2.0. Microsoft Corporation. URL:
Scalable Vector Graphics (SVG) 1.0 Specification. Jon Ferraiolo. W3C. 4 September 2001. W3C Recommendation. URL:
SVG Accessibility API Mappings. Amelia Bellamy-Royds; Richard Schwerdtfeger. W3C. 8 September 2016. W3C Working Draft. URL:
UI Automation. Microsoft Corporation. URL:
The IAccessibleEx Interface. Microsoft Corporation. URL:
Accessible Rich Internet Applications (WAI-ARIA) 1.0. James Craig; Michael Cooper et al. W3C. 20 March 2014. W3C Recommendation. URL:
Accessible Rich Internet Applications (WAI-ARIA) 1.1. Joanmarie Diggs; Shane McCarron; Michael Cooper; Richard Schwerdtfeger; James Craig. W3C. 14 December 2017. W3C Recommendation. URL:
WAI-ARIA Authoring Practices 1.1. Matthew King; James Nurthen; Michiel Bijl; Michael Cooper; Joseph Scheuhammer; Lisa Pappas; Richard Schwerdtfeger. W3C. 14 December 2017. W3C Note. URL:
Web Content Accessibility Guidelines (WCAG) 2.0. Ben Caldwell; Michael Cooper; Loretta Guarino Reid; Gregg Vanderheiden et al. W3C. 11 December 2008. W3C Recommendation. URL: