SVG Accessibility API Mappings

SVG Accessibility API Mappings (SVG-AAM) defines how user agents map Scalable Vector Graphics (SVG) [[!SVG]] markup to platform accessibility application programming interfaces (APIs). It is intended for SVG user agent developers responsible for SVG accessibility in their user agent.

This specification extends the Core Accessibility API Mappings 1.1 (CORE-AAM) [[!CORE-AAM]] and the Accessible Name and Description: Computation and API Mappings 1.1 (ACCNAME-AAM) [[!ACCNAME-AAM]] specifications for user agents. It leverages those core mappings and provides SVG-specific guidance to define how the SVG user agent must respond to keyboard focus and Role; State and Property attributes provided in Web content via WAI-ARIA [[!WAI-ARIA]]. The SVG-AAM also adapts the ACCNAME-AAM to make use of standard SVG features used to compute accessible names and description information exposed by platform accessibility APIs. These features allow SVG authors to create accessible rich internet applications, including charts, graphs, and other drawings.

The SVG-AAM is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

Introduction

In traditional Graphical User Interface (GUI) applications, components of the User Interface (UI) are displayed when needed and hidden when not needed based on user interactions. Accessibility APIs are used to communicate semantic information about the user interface to assistive technology software used by people with disabilities. These APIs constitute a contract between applications and assistive technologies, such as screen readers, magnifiers, alternate input devices, and speech command and control, to enable them to access the appropriate semantics needed to produce a usable alternative to interactive applications. For example, screen reading software for blind users can determine whether a particular UI component is a menu, button, text field, list box, etc.

In traditional SVG documents most SVG elements do not provide semantic information of value to assistive technologies as they represent low level vector graphics drawing directives. Consequently, it is when the author provides alternative text, descriptions, or WAI-ARIA semantics when that element has meaning to assistive technologies. SVG 2 now incorporates traditional keyboard navigation from HTML 5. Therefore, the user agent provides focus navigation to SVG elements known to receive focus by default or to that may receive focus through the use of tabindex. Assistive technologies obtain the essential semantic information from the Document Object Model (DOM) through user agent mappings to platform Accessibility API.

Both Scalable Vector Graphics (SVG) 1 [[SVG1]] and Scalable Vector Graphics (SVG) 1.1 [[SVG11]] included elements for accessibility purposes, such as <title> and <desc> , but prior to this specification there was no normative guidance as to how user agents should expose this information to assistive technologies, or how to integrate it with host languages and validators that support WAI-ARIA.

SVG closely aligns with the DOM Level 3 Core and HTML5 events to facilitate JavaScript use. Through the use of technologies such as JavaScript, Ajax, and CSS authors can make SVG look and behave more interactive without having to reload the page with each user interaction. In SVG, authors are able to produce accessible rich interactive charts, and drawings allowing the author to dynamically supply their intended semantics through through the use of WAI-ARIA. WAI-ARIA enables rich SVG drawn Internet applications to have the same accessibility features as GUI applications. Authors may include WAI-ARIA in their markup and user agents translate the WAI-ARIA markup to the platform accessibility APIs.

For an introduction to WAI-ARIA, see the WAI-ARIA Overview. The Core Accessibility API Mappings specification how WAI-ARIA roles, states, and properties should be supported in user agents using platform accessibility APIs. It is part of a set of resources that define and support the WAI-ARIA specification which includes the following documents:

Accessible Rich Internet Applications (WAI-ARIA) 1.1 [[WAI-ARIA]], a planned W3C recommendation follow on, to the [[WAI-ARIA-10]] standard standard.
WAI-ARIA Authoring Practices Guide [[ARIA-PRACTICES]], a planned W3C Working Group Note, describes how web content developers can develop accessible rich internet applications using WAI-ARIA. It provides detailed advice and examples directed primarily to web application developers, yet also useful to user agent and developers of assistive technologies.

This specification begins by providing a general overview of accessibility APIs and the accessible object hierarchy known as the accessibility tree. The following sections define how SVG host language elements, with or without WAI-ARIA roles, states, and properties applied map content to accessibility APIs. Other sections give guidance on calculating text alternatives, mapping actions to events, event processing, special document handling procedures, and error handling.

This guide relies heavily on the accessibility API mappings defined in the [[CORE-AAM]] and [[ACCNAME-AAM]] specifications but defines changes in mappings due to features in the [[SVG]] host language. Key areas of difference are:

Intrinsic host language semantics
Text computation of names and descriptions

Accessibility APIs

To provide access to desktop GUI applications, assistive technologies originally used heuristic techniques to determine the meaning of the user interface and build an alternative off-screen model. For example, a row of labels displayed horizontally near the top of an application window might be a menu. Labels with a border drawn around them might be buttons. Heuristic techniques are not always accurate, however, and require assistive technologies to be updated whenever the software application is updated.

A much better technique is for the software application to provide the necessary information for interoperability with assistive technology. To meet this need, platform owners have developed specialized interfaces, called accessibility API s, which can be used to communicate accessibility information about user interfaces to assistive technologies.

In Web pages the Document Object Model (DOM) is used to represent the structure and state of the elements in the document being rendered by a user agent. The elements of the document are organized into a hierarchy of nodes known as the DOM tree. User agents map DOMto accessibility APIs in the same way desktop applications map UI components do to support assistive technologies with the expectation that the information passed from the DOM matches the semantic intent of the author.

When the first rich Internet applications came out, authors created custom UI controls where the author created content that visibly matched the intent of the author but not the semantic intent. This is because there was no vehicle in early versions of HTML or SVG to provide the necessary semantics needed for user agents to expose them to assistive technologies through the platform accessibility APIs of the underlying operating system, throughout a web applications life cycle. This problem is worse in SVG as most its elements have no intrinsic host language semantics that make sense to users of assistive technologies as it consists primarily of low level drawing calls. Today, the information needed is provided when developers use WAI-ARIA to supply semantics in the form of role, state, and property information for elements. The screen reader or other assistive technology uses the semantic information exposed via the accessibility API to provide an alternative rendering of an application that is meaningful to a user.

Accessibility APIs covered by this document are:

Microsoft Active Accessibility 2.0 [MSAA] with UIA Express [UIA-EXPRESS]
MSAA with IAccessible2 1.3 [IA2]
User Interface Automation [UIA-ARIA]
Linux Accessibility Toolkit 2.10.0 [ATK] and Assistive Technology - Service Provider Interface 2.1 [AT-SPI]
Mac OS X Accessibility Protocol Mac OS 10.10 [[AXAPI]]

If user agent developers need to expose information using other accessibility APIs, it is recommended that they work closely with the developer of the platform where the API runs, and assistive technology developers on that platform.

The Accessibility Tree and the DOM Tree

The accessibility tree and the DOM tree are parallel structures. Roughly speaking the accessibility tree is a subset of the DOM tree. It includes the user interface objects of the user agent and the objects of the document. Accessible objects are created in the accessibility tree for every DOM element that should be exposed to an assistive technology, either because it may fire an accessibility event or because it has a property, relationship or feature which needs to be exposed. Generally if something can be trimmed out it will be, for reasons of performance and simplicity. For example, a <span> with just a style change and no semantics may not get its own accessible object, but the style change will be exposed by other means.

Mapping WAI-ARIA to Accessibility APIs

WAI-ARIA support was first introduced to SVG in Scalable Vector Graphics (SVG) 2 [[SVG2]]. This section defines how WAI-ARIA semantics are exposed to assistive technologies through platform Accessibility APIs and how SVG elements are mapped to Accessibility APIs based on WAI-ARIA.

General rules for exposing WAI-ARIA semantics

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

Conflicts between native markup semantics and WAI-ARIA

SVG user agents MUST conform to Conflicts between native markup semantics and WAI-ARIA in [[!CORE-AAM]] where the host language is [[SVG]].

Exposing attributes that do not directly map to accessibility API properties

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

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.

General Rules

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

SVG Element Mapping Table

This section defines how elements in SVG2 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.

^{[Note 1]} Issue 698: Need to address mappings when tabindex or aria relationships are applied to elements whose native host language semantics have a role="none". Typically these should not be mapped. tabindex is allowed on all elements even though authors are unlikely to do it.

^{[Note 2]} Issue 699: Address use of map to generic container vs. a "group" role and role="none" mapping to concrete objects in some platforms. A role of "none" should not be mapped unless there is an error condition to avoid unnecessary growth of the accessibility tree.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
SVG ELement	Default Platform WAI-ARIA Role Mappings	Platform WAI-ARIA Role Mappings for each WAI-ARIA Role Applied
`a`	`link`	`Role Mappings`
`animate`	`none`	`Role Mappings`
`animateMotion`	`none`	`Role Mappings`
`animateTransform`	`none`	`Role Mappings`
`audio`	Map to `group` except for platform ATK/ATSPI that maps to role: `ATK_ROLE_AUDIO`	`application`
`canvas`	`group`	`Role Mappings`
`circle`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`clipPath`	`none`	`Role Mappings`
`cursor`	`none`	`Role Mappings`
`defs`	`none`	No role may be applied.
`desc`	`none`	No role may be applied.
`discard`	`none`	No role may be applied.
`ellipse`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`feBlend`	`none`	No role may be applied.
`feColorMatrix`	`none`	No role may be applied.
`feComponentTransfer`	`none`	No role may be applied.
`feComposite`	`none`	No role may be applied.
`feConvolveMatrix`	`none`	No role may be applied.
`feDiffuseLighting`	`none`	No role may be applied.
`feDisplacementMap`	`none`	No role may be applied.
`feDistantLight`	`none`	No role may be applied.
`feDropShadow`	`none`	No role may be applied.
`feFlood`	`none`	No role may be applied.
`feFuncA`	`none`	No role may be applied.
`feFuncB`	`none`	No role may be applied.
`feFuncG`	`none`	No role may be applied.
`feFuncR`	`none`	No role may be applied.
`feGaussianBlur`	`none`	No role may be applied.
`feImage`	`none`	No role may be applied.
`feMerge`	`none`	No role may be applied.
`feMergeNode`	`none`	No role may be applied.
`feMorphology`	`none`	No role may be applied.
`feOffset`	`none`	No role may be applied.
`fePointLight`	`none`	No role may be applied.
`feSpecularLighting`	`none`	No role may be applied.
`feSpotLight`	`none`	No role may be applied.
`feTile`	`none`	No role may be applied.
`feTurbulence`	`none`	No role may be applied.
`filter`	`none`	No role may be applied.
`foreignObject`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`g`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`hatch`	`none`	No role may be applied.
`hatchPath`	`none`	No role may be applied.
`iframe`	`none`	`application`, `document`, `img`
`image`	`img`	No role may be applied.
`line`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`linearGradient`	`none`	No role may be applied.
`marker`	`none`	No role may be applied.
`mask`	`none`	No role may be applied.
`meshGradient`	`none`	No role may be applied.
`meshPatch`	`none`	No role may be applied.
`meshRow`	`none`	No role may be applied.
`metadata`	`none`	No role may be applied.
`mpath`	`none`	No role may be applied.
`path`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`pattern`	`none`	No role may be applied.
`polygon`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`polyline`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`radialGradient`	`none`	No role may be applied.
`rect`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`script`	`none`	No role may be applied.
`set`	`none`	No role may be applied.
`solidColor`	`none`	No role may be applied.
`source`	`none`	No role may be applied.
`stop`	`none`	No role may be applied.
`style`	`none`	No role may be applied.
`svg`	`group`	`Role Mappings`
`switch`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`symbol`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`text`	The use of the group role here is that of generic container for text. More work is required to address what additional text interfaces are exposed through platform accessibility API services. `group`
`textPath`	The use of the group role here is that of generic container for text. More work is required to address what additional text interfaces are exposed through platform accessibility API services. `group`
`title`	`none`	No role may be applied.
`track`	`none`	No role may be applied.
`tspan`	The use of the group role here is that of generic container for text. More work is required to address what additional text interfaces are exposed through platform accessibility API services. `group`
`use`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribute; otherwise, `group` role mapping	`Role Mappings`
`video`	Map to `group` except for platform ATK/ATSPI that maps to role: `ATK_ROLE_VIDEO`	`application`
`view`	`none` role mapping, provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, or ‘aria-describedby’ attribu oe; otherwise, `group` role mapping	`Role Mappings`

State and Property Mapping

This section describes how to expose WAI-ARIA states and object properties. SVG user agents MUST conform to the State and Property Mapping accessibility API computational requirements in [[!CORE-AAM]].

Special Processing Requiring Additional Computation

Name and Description

When computing an accessible name or accessible description, user agents MUST conform to the section titled Text Alternative Computation of the [[!ACCNAME-AAM]] specification with the following modifications for the SVG host language:

Replace step 2D with the following:
Otherwise, if performing a text alternative computation for an accessible name and the current node provides a descendant <title> element chosen based on the language rules for the SVG specification, return the title text alternative as a flat string, unless the element is marked as presentational (role="presentation" or role="none"). If performing a text alternative computation for an accessible description, and the current node provides a descendant <desc> chosen based on the language rules for the SVG specification; return the description text alternative an accessible description computation attribute as presentational (role="presentation" or role="none").
In step 2F skip step iii of Text Alternative Computation

Widget Values

SVG user agents MUST conform to the Widget Values accessibility API computational requirements in [[!CORE-AAM]].

Relations

SVG user agents MUST conform to the Relation accessibility API computational requirements in [[!CORE-AAM]].

Group Position

SVG user agents MUST conform to the Group Position accessibility API computational requirements in [[!CORE-AAM]].

Actions

SVG user agents MUST conform to the Actions accessibility API computational requirements in [[!CORE-AAM]].

Events

User agents fire events for user actions, WAI-ARIA state changes, changes to document content or node visibility, changes in selection, and operation of menus. Conforming user agents MUST support the [[!CORE-AAM]] Events mappings.