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 allows SVG authors to create accessible rich internet applications, including charts, graphs, and other drawings. It does this by extending 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.

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

This is a First Public Working Draft of SVG Accessibility API Mappings 1.0 by the SVG Accessibility Task Force, a joint task force of the Protocols & Formats Working Group and the SVG Working Group. It provides the first concrete guidance on mapping SVG language features to accessibility APIs, and addresses both native SVG features and ARIA additions. It extends Core Accessibility API Mappings 1.1 and Accessible Name and Description: Computation and API Mappings 1.1, and is part of a suite of similar technology-specific Accessibility API Mappings specifications.

Feedback on any aspect of the specification is accepted. For this publication, the SVG Accessibility Task Force particularly seeks feedback on the following questions:

The editors have highlighted particularly problematic aspects of the specification, or areas where further clarification is likely to be required, in the form of Editor's Notes boxes throughout the text. Comments on these issues would be particularly appreciated.

To comment, send email to public-svg-a11y@w3.org (comment archive) or file an issue in W3C Bugzilla. Comments are requested by 27 March 2015. In-progress updates to the document may be viewed in the publicly visible editors' draft.

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 semantics about the user interface to assistive technologies 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 or complex documents. For example, screen-reading software for blind users can determine whether a particular UI component is a menu, button, text field, list box, etc. It can also present the information in tables or lists in a way that provides context for each piece of text.

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.

In traditional SVG documents, most SVG elements do not provide semantic information of value to assistive technologies. Instead, they represent low-level vector graphics drawing directives. That element only has meaning to assistive technologies if the author provides alternative text, descriptions, or WAI-ARIA semantics.

Both Scalable Vector Graphics (SVG) version 1 [[SVG1]] and version 1.1 [[SVG11]] included elements for accessibility purposes, such as <title> and <desc>. However, 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 2 now incorporates traditional keyboard navigation from HTML 5. The user agent provides sequential focus navigation to SVG elements that are interactive by default (links and audio/video elements with controls), or that the author has indicated may receive focus (through the use of tabindex attribute). Focus may also be set or removed programmatically by scripts, so that authors may implement more complex keyboard focus patterns.

SVG closely aligns with 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. With SVG, authors are able to produce rich interactive charts and drawings.

To allow the author to express and dynamically update their intended semantics, SVG 2 supports the use of WAI-ARIA roles, states, and properties. WAI-ARIA enables rich SVG-drawn Internet applications to have the same accessibility features as GUI applications installed on their operating system. Authors may include WAI-ARIA attributes in their markup and user agents will translate it to the platform accessibility APIs.

For an introduction to WAI-ARIA, see the WAI-ARIA Overview. The SVG Accessibility API Mappings specification (this document) defines how WAI-ARIA features interact with the native semantics of the SVG language. It is part of a set of resources that define and support the WAI-ARIA specification, including the following documents:

This specification begins by providing a general overview of accessibility APIs and the hierarchy of accessible objects known as the accessibility tree. The following sections define how SVG host language elements and content — with or without WAI-ARIA roles, states, and properties applied — map 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 stem from the intrinsic host language semantics of SVG:

Accessibility APIs

To provide access to GUI applications, software applications expose the necessary information needed by assistive technologies to interoperate with it through accessibility APIs. The accessibility information exposed through the accessibility APIs must be maintained throughout the applications lifecycle.

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 DOM to accessibility APIs, in the same way desktop applications map UI components. The information provided to the accessibility API is used to support assistive technologies, with the expectation that the information passed from the DOM matches the semantic intent of the author. The author may communicate this semantic intent by using native features of the document language or by using WAI-ARIA, if native features are not available.

Authors use SVG to create a broad range of applications and drawings. The information needed to support accessibility APIs in SVG comes from a combination of semantics from the elements themselves but also the additional semantics provided by WAI-ARIA and the modular extensions to WAI-ARIA supported by this specification.

A 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 supported by this document (and the other specifications it extends) are:

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, augmented to include the user interface objects of the user agent as well as 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. An element could be exposed 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 omitted 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.

Normative User Agent Implementation Requirements for SVG

This specification indicates whether a section is normative or informative and the classification applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.

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 a strong 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.

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.

Important Terms

Placeholder for glossary

The definition of hidden used here may need to be clarified; see notes in the section Excluding Elements from the Accessibility Tree.

Supporting Keyboard Navigation

Enabling keyboard navigation in web applications is a necessary step toward making accessible web applications possible. Not only is the keyboard the primary input device for many users, but other accessibile input devices use keyboard events to communicate with the user agent.

The Scalable Vector Graphics (SVG) 1 [[SVG1]] and 1.1 [[SVG11]] specifications included only very limited keyboard support (access keys for animations). Many user agents implemented tabbed focus for links, but there was no declarative or scripted means for authors to control this behavior. Scalable Vector Graphics (SVG) 2 [[SVG2]] introduces keyboard navigation and focus control based on the HTML tabindex model.

Conforming user agents MUST conform to Supporting Keyboard Navigation requirements in [[!CORE-AAM]].

The SVG Accessibility Task Force intends to develop more detailed guidelines for authors and user agents regarding navigation in graphical documents.

Mapping WAI-ARIA to Accessibility APIs

WAI-ARIA support was formally introduced to SVG in Scalable Vector Graphics (SVG) 2 [[SVG2]], which allows ARIA attributes to be used in the default namespace. 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

SVG user agents MUST conform to General rules for exposing WAI-ARIA semantics in [[!CORE-AAM]], with the additions described in the following sub-sections.

Excluding Elements from the Accessibility Tree

Certain elements in the DOM are not exposed via the accessibility API. The section Excluding Elements from the Accessibility Tree of the Core Accessibility API Mappings [[CORE-AAM]] outlines the general rules for excluding elements. One factor is whether host language semantics specify that the element should not be displayed.

The SVG language defines numerous elements that fit this criteria. Many SVG elements are never directly rendered to the screen, while others may or may not be rendered or displayed, depending on context or CSS styling. Elements which are neither perceivable nor interactive should not be included in the accessibility tree exposed to accessibility APIs. This section details the expected interpretation of SVG host language semantics.

The other factors for excluding elements, as described in the Core Accessibility API Mappings, are as follows:

  • If the first mappable role provided by the author is none or presentation, the element must not be exposed.
  • If the element or an ancestor has an aria-hidden value of true, it should not be exposed.
  • If an ancestor of the element has a used role which has the characteristic "Children Presentational: True" in the WAI-ARIA specifications [[WAI-ARIA]], the child element should not be exposed. For example, the roles button and img exclude all child content from being directly included in the accessibility tree.

Consult the original document [[CORE-AAM]] for the normative text.

Elements which are never directly rendered to screen, nor represented by an interactive region in a graphic, do not need a corresponding accessible object. User agents MUST NOT include any elements, or their descendant content, as an accessible object in the accessibility tree that are indicated as no accessible object created in the SVG Element Mapping Table. User agents SHOULD also exclude any other element defined by past or future SVG specifications or modules that specifically indicate the element is never directly rendered.

For example, elements that represent filters, gradients, or gradient stops will never create an accessible object. Shape elements or image elements that are included in an SVG definitions section or as part of a pattern will also not have accessible objects, because the semantics of the ancestor defs or pattern element preclude that entire DOM subtree from being represented in the accessibility tree.

Elements that are excluded from the accessibility tree might still be used in the name and description computation of another element, as defined in the Name and Description section.

Although they are not directly included in the accessibility tree, animation and view elements can affect the accessible objects representing their target elements, as described under Special Processing Requiring Additional Computation.

In addition, SVG 1.1 [[SVG11]] defines the conditional processing attributes systemLanguage, requiredExtensions, and requiredFeatures. These may be used individually or in combination with the switch element to prevent content from being rendered under certain conditions, or to select between alternate versions of content.

SVG user agents MUST NOT expose to accessibility APIs any elements that are not rendered because of conditional processing attributes on that element or because of the position of that element within a switch construct. The switch element itself SHOULD be omitted as if it had a role of none or presentation.

The rendering of SVG elements is also affected by CSS styling properties, which may be specified using stylesheet rules, inline styles, presentation attributes, or animations. Regardless of how the style property is specified, the effect depends on the final computed value determined by the CSS cascade [[CSS-CASCADE-3]]. User agents MUST NOT expose to accessibility APIs any element that is not rendered because its computed style includes a value of none for the display property.

Other style properties can prevent an element, which is otherwise part of the rendering tree, from creating any visible representation in the rendered graphic. Such elements may still be interactive; they may receive keyboard focus or they may be associated with a region of the graphic that is responsive to pointer input events.

For the purpose of SVG, an element is considered hidden if it is neither visible nor interactive, and is therefore not perceivable to visual users. User agents SHOULD NOT expose to accessibility APIs any element that is hidden in this sense. This includes elements that have the following computed style values, unless the element can receive user input (pointer events or keyboard focus) as described under Including Elements in the Accessibility Tree:

  • a value of hidden for the visibility property
  • a value of none for both the fill and stroke properties of text or shape elements

An element that is currently positioned off-screen, or that is obscured by other elements, is not considered hidden. User agents should expose this state through other means, as described in the State and Property Mapping section of the Core Accessibility API Mappings [[CORE-AAM]].

The opacity property (of an element itself or an ancestor element) can make an element invisible. However, this is not considered a hiding method that excludes elements from the accessibility tree.

Opacity (unlike the fill, stroke, and visibility properties) does not affect pointer-events processing. Furthermore, opacity is often animated, e.g. to create a blinking effect, which would problematic if this led to repeated changes in the accessibility tree.

Authors are therefore advised not be rely on zero opacity to hide inactive content. If opacity is used to fade out no-longer relevant content, the aria-hidden attribute can be used to indicate that assistive technologies should ignore the element and its descendents.

In addition to these non-displayed elements, many SVG elements—although rendered to the screen—do not have an intrinsic semantic meaning. Instead, they represent components of the visual presentation of the document. To simplify the accessible representation of the document, these purely presentational elements would normally be omitted from the accessibility tree, unless the author explicitly provides semantic content.

The following elements in the SVG namespace SHOULD NOT be included in the accessibility tree, except as described under Including Elements in the Accessibility Tree:

  • shape elements (circle, ellipse, line, path, polygon, polyline, rect)
  • the use element
  • the grouping (g) element
  • the image element
  • text formatting elements (textPath, tspan)
  • the foreignObject element

Although these elements are omitted from the accessibility tree, their child content is still processed, as if it was a direct child of the nearest ancestor node in the DOM tree that is included in the accessibility tree. In other words, the markup elements are treated as if they had a role of none or presentation.

The strict exclusion of non-rendered metadata elements, including desc, from the accessibility tree means that their content will only be available as plain text, not as structured alternative representations that a user can navigate in browsing mode.

This contradicts the original intent of the SVG specifications, which allows these elements to include structured content, including HTML-namespaced content. The SVG 1 specifications had suggested that this could be alternatively presented as CSS-formated XML text, but this is not supported by the user agent/assistive technology combinations currently in use.

The editors welcome feedback and suggestions on alternative ways to represent this hidden alternative content in a way consistent with user agent and accessibility API implementations.

The definition of hidden elements used here is more complex than that currently suggested in the Core mapping document [[CORE-AAM]]. The CORE-AAM spec implies that invisible elements (visibility: hidden) would be treated equivalent to un-rendered elements (display: none).

For SVG, this is not always appropriate. In many cases, the invisible hidden elements are of semantic importance (because they are interactive) while visible elements are presentational only. For example, large invisible elements are often used to provide easy-to-hit targets for points in a map or datachart. Because these elements react to pointer events, they are effectively perceivable to pointer users, and should be perceivable and interactive to users of assistive technologies as well.

The editors of this document will be coordinating with the editors of CORE-AAM to develop clear and universal guidance. Feedback from authors and implementers is appreciated.

Including Elements in the Accessibility Tree

Any rendered SVG element may have semantic meaning. Authors indicate the significance of the element by including alternative text content or WAI-ARIA attributes.

SVG user agents MUST provide an accessible object in the accessibility tree for rendered SVG elements that meet any of the following criteria:

At the time of drafting this document, those criteria are as follows:

The latest version of the source document [[CORE-AAM]] should be consulted for the normative text.

The exception for hidden elements means that SVG metadata elements or other non-rendered content may be used in the accessible name and description of another element without themselves being included in the accessiblity tree. For example, current best practice for fallback browser support is to use aria-labelledby and aria-describedby to redundantly link to title and desc child elements. Including these elements as separate nodes in the tree would unnecessarily complicate the document presented to screen reader users.

Interactive elements are covered by the requirement regarding elements that may fire an Accessibility API event. For SVG, this specifically means that elements that would normally be included in the accessibility tree except for the fact they are invisible (e.g., because of the visibility: hidden style property, or a combination of fill: none and stroke: none for shapes or text) should nonetheless be included in the accessibility tree if they can receive user input events. Particular examples to consider:

  • A rendered but invisible element with certain values for the pointer-events property (bounding-box, painted, fill, stroke, or all) may receive pointer events, according to the rules for that property.
  • A rendered but invisible element with a non-empty value for the tabindex attribute may receive keyboard focus and therefore keyboard input events.

Elements that are interactive in either of these ways MUST be included in the accessbility tree.

A container element that is itself hidden (e.g., via the visibility property) may have children that are visible and/or can receive events. If the child elements would otherwise be excluded from the accessibility tree because they lack semantic information, the nearest ancestor element that meets the criteria for inclusion SHOULD instead be treated as if it was visible or was able to receive events. Similarly, a use element may include visible or interactive component graphics, despite having style properties that would cause an individual shape element to be hidden. The use element SHOULD be considered visible or interactive if any of its re-used content is visible or interactive.

The tabindex attribute and the pointer-events property have no impact on elements which are not rendered at all, because of the display: none property or because of host language semantics.

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]] and the native semantics are as described in the SVG Element Mapping Table, the State and Property Mapping section, and the Special Processing Requiring Additional Computation section.

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.

WAI-ARIA only supports one active role at a time. However, multiple roles may 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 font families in case the first choice font is not supported. This allows the role taxonomy to be extended in future for specialized applications. The entire role string is exposed to accessibility technologies where possible, so they can respond appropriately even if there is no equivalent role in the platform API.

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 WAI-ARIA roles and platform accessibility APIs based on their native host language semantics, including which WAI-ARIA roles may be applied. This section refers directly to both the Role Mappings in the Core Accessibility API Mappings [[!CORE-AAM]] specification and the Role Mappings in the Graphics Accessibility API Mappings [[!GRAPHICS-AAM]] specification, which define how WAI-ARIA roles are mapped to platform accessibility APIs.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
SVG Element Default Platform WAI-ARIA Role Mappings Allowed WAI-ARIA Roles and Platform WAI-ARIA Role Mappings
a link any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
animate no accessible object created no role may be applied
animateMotion no accessible object created no role may be applied
animateTransform no accessible object created no role may be applied
audio Follow the recommendations for the HTML audio element in the HTML Accessibility API Mappings specification [[!HTML-AAM]]. application role
canvas Follow the recommendations for the HTML canvas element in the HTML Accessibility API Mappings specification [[!HTML-AAM]]. any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
circle img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
clipPath no accessible object created no role may be applied
cursor no accessible object created no role may be applied
defs no accessible object created, for this element or any child content no role may be applied
desc no accessible object created; see Name and Description mapping no role may be applied
discard no accessible object created no role may be applied
ellipse img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
feBlend no accessible object created no role may be applied
feColorMatrix no accessible object created no role may be applied
feComponentTransfer no accessible object created no role may be applied
feComposite no accessible object created no role may be applied
feConvolveMatrix no accessible object created no role may be applied
feDiffuseLighting no accessible object created no role may be applied
feDisplacementMap no accessible object created no role may be applied
feDistantLight no accessible object created no role may be applied
feDropShadow no accessible object created no role may be applied
feFlood no accessible object created no role may be applied
feFuncA no accessible object created no role may be applied
feFuncB no accessible object created no role may be applied
feFuncG no accessible object created no role may be applied
feFuncR no accessible object created no role may be applied
feGaussianBlur no accessible object created no role may be applied
feImage no accessible object created no role may be applied
feMerge no accessible object created no role may be applied
feMergeNode no accessible object created no role may be applied
feMorphology no accessible object created no role may be applied
feOffset no accessible object created no role may be applied
fePointLight no accessible object created no role may be applied
feSpecularLighting no accessible object created no role may be applied
feSpotLight no accessible object created no role may be applied
feTile no accessible object created no role may be applied
feTurbulence no accessible object created no role may be applied
filter no accessible object created no role may be applied
foreignObject group role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
g group role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
hatch no accessible object created no role may be applied
hatchPath no accessible object created no role may be applied
iframe Follow the recommendations for the HTML iframe element in the HTML Accessibility API Mappings specification [[!HTML-AAM]]. application, document, img
image img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
line img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
linearGradient no accessible object created no role may be applied
marker no accessible object created no role may be applied
mask no accessible object created no role may be applied
mesh img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
meshPatch no accessible object created no role may be applied
meshRow no accessible object created no role may be applied
metadata no accessible object created no role may be applied
mpath no accessible object created no role may be applied
path img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
pattern no accessible object created, for this element or any child content no role may be applied
polygon img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
polyline img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
radialGradient no accessible object created no role may be applied
rect img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
script no accessible object created no role may be applied
set no accessible object created no role may be applied
solidColor no accessible object created no role may be applied
source Follow the recommendations for the HTML source element in the HTML Accessibility API Mappings specification [[!HTML-AAM]]. no role may be applied
stop no accessible object created no role may be applied
style no accessible object created no role may be applied
svg group

The group role is used as a generic container; this default may be replaced by one of the new roles proposed in the ARIA Graphics module. Further work is required to determine the most appropriate role mapping for each platform API.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
switch no accessible object created no role may be applied
symbol no accessible object created, for this element or any child content no role may be applied
text group role, but with the following platform-specific API mappings:
MSAA + IAccessible2
Role: IA2_ROLE_PARAGRAPH
Interfaces: IAccessibleText2; IAccessibleHypertext2
UIA
Control Type: Text
ATK
Role: ATK_ROLE_SECTION
Interfaces: AtkText; AtkHypertext
AX
AXRole: AXGroup
AXSubrole: (nil)
AXRoleDescription: "group"

The platform mappings given above are the same as those recommended for the HTML p element in the HTML Accessibility API Mappings specification [[HTML-AAM]]. There is currently no WAI-ARIA role available that defines a distinct text block. However, such roles (denoting paragraphs or distinct text regions) exist in many platform accessibility APIs and are therefore used instead of a generic group role.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
textPath group role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created, but changes in text styling SHOULD be exposed through properties of the parent text element where supported

The use of the group role here is that of generic container for a span of text content which forms a distinct object (either because it has supplementary alternative text labels or descriptions or because it is interactive). More work is required to address whether text-specific platform accessibility API roles can more effectively serve this function.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
title no accessible object created; see Name and Description mapping no role may be applied
track Follow the recommendations for the HTML track element in the HTML Accessibility API Mappings specification [[!HTML-AAM]]. no role may be applied
tspan group role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created, but changes in text styling SHOULD be exposed through properties of the parent text element where supported

The use of the group role here is that of generic container for a span of text content which forms a distinct object (either because it has supplementary alternative text labels or descriptions or because it is interactive). More work is required to address whether text-specific platform accessibility API roles can more effectively serve this function.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
use img role mapping if the element meets the criteria for Including Elements in the Accessibility Tree; otherwise, no accessible object created; see Name and Description mapping for special rules for use elements

If a symbol role is introduced, as proposed by the ARIA graphics module, it would become the default mapping where supported; further work is required to determine how this role would map to platform APIs.

As currently proposed by this specification, the re-used graphical elements would not be exposed directly, although they can affect the name and description calculation.

This is reflected in the default roles. Both the img role and proposed graphics-symbol role create atomic objects; any child content is assumed presentational. Assigning these roles to a use element implies that the graphic drawn with that element is accessible only as a single entity, not as distinct component parts.

This is consistent with most SVG content containing use elements, for which the re-used graphic is a simple icon or image. It is also consistent with the desire to simplify the accessibility tree as much as possible.

However, it is not consistent with models in the SVG specifications that allow individual cloned graphic components to receive and propagate user input (pointer) events. The SVG 1.1 specifications [[SVG11]] defined a non-exposed document tree consisting of SVGElementInstance objects which could be the targets of pointer events handled by event handlers on the use or an ancestor element; keyboard accessibility was not considered.

At the time of writing, the SVG 2 specifications [[SVG]] propose significantly overhauling this model in favour of one based on the Shadow DOM specification [[SHADOW-DOM]]. The full impact of this change on event handling and accessiblity, particularly keyboard accessibility, has not yet been explored.

In order to support a complex and interactive shadow DOM, special processing rules would be required to generate an accessibility subtree representing the cloned content. Two options would then be available:

  • continue to use the img/graphics-symbol roles by default, and therefore only create a cloned subtree if the author specifically assigns a different role, or
  • use a different default role such as group or the proposed graphics-object, which support complex child content.

Any changes would also have an impact on the appropriate treatment of use references in the Name and Description computation; see the note in that section for more issues.

The editors welcome feedback about the appropriate default and possible behaviors, and would be particularly interested in any practical examples of complex re-used content where a cloned DOM needs to be available to assistive technologies to ensure accessibility.

any role; see the Core Accessibility API Role Mappings and the Graphics Accessibility API Role Mappings
video Follow the recommendations for the HTML video element in the HTML Accessibility API Mappings specification [[!HTML-AAM]]. application role
view no accessible object created; see the section SVG views for special processing requirements no role may be applied

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]].

In addition, the following attributes on SVG elements require special processing:

The xlink prefix is used here to refer to the XLink namespace, http://www.w3.org/1999/xlink. Attributes of the given names in that namespace should be processed as described here, regardless of how the namespace is applied in markup or via script. XLink-namespaced attributes are deprecated in SVG 2 [[SVG]], but user agents are still expected to process them, to maintain backwards compatibility. Nonetheless, SVG 2 requires that the href attribute in the default namespace takes precedence over the XLink equivalent if both are set on a given element. In that case, the XLink version is not valid for the purpose of the name and description computation.

The effective attribute for a given element, and therefore the state and property mapping, may be affected by declarative animation as described in the Animation section.

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:

  1. Replace step 2A with the following:
    If the current node traversal is not a result of following aria-labelledby, aria-describedby or a use element reference, and the current node is not included in the accessibility tree according to the rules in Excluding Elements from the Accessibility Tree and Including Elements in the Accessibility Tree, return the empty string.
  2. Replace step 2D with the following:

    Otherwise, if performing a text alternative computation for an accessible name:

    • If the current node has at least one direct child title element, select the appropriate title based on the language rules for the SVG specification, and return the title text alternative as a flat string.
    • If the current node is a link, and there was no child title element, but it has an xlink:title attribute, return the value of that attribute.
    • If the current node is a use element, and there was no child title element, but it has a valid href or xlink:href attribute pointing to another element in the same document, set the current node to the referenced element and compute the text alternative from step 2 as if that element had been referenced with aria-labelledby.

    If performing a text alternative computation for an accessible description:

    • If the current node has at least one direct child desc element, select the appropriate description based on the language rules for the SVG specification, and return the concatenated text content of the description.
    • If the current node is a use element, and there was no child desc element, but it has a valid href or xlink:href attribute pointing to another element in the same document, set the current node to the referenced element and compute the text alternative from step 2 as if that element had been referenced with aria-describedby.
  3. In step 2F, modify step iii by replacing:

    For each child node of the current node:

    with

    If the element is a text container element, for each child node of the current node:

  4. Replace step 2H with the following:

    Otherwise, if performing a text alternative computation for an accessible description, and the current node has at least one direct child title element, but the title elements were not used when generating the accessible name for the node, then select the appropriate title based on the language rules for the SVG specification, and return the title text content as the description.

The net effect of these changes is to establish the following priority of alternative text values for the accessible name:

  1. aria-labelledby
  2. aria-label
  3. a direct child title element
  4. xlink:title attribute
  5. for a use element, the accessible name calculated for the re-used content
  6. for text container elements, the text content

The alternative text values for the accessible description have the following priority:

  1. aria-describedby
  2. a direct child desc element
  3. for a use element, the accessible description calculated for the re-used content
  4. for text container elements, the text content
  5. a direct child title element that provides a tooltip, when ARIA label attributes are used to provide a different accessible name

The aria-labelledby and aria-describedby properties can reference the element on which they are given, in order to concatenate one of the other text alternatives with text from a separate element.

One of the effects of the given procedure is that descriptive text and labels provided for use elements replace the equivalent alternative text provided for the source graphics. If an author wished to combine descriptions for the general and specific instances, an aria-labelledby or aria-describedby attribute would need to explicitly point to both the source graphic and the use instance.

A simple example would be as follows: 

  <defs>
    <circle id="c" r="1cm">
      <desc>A 1cm-radius circle</desc>
    </circle>
  </defs>
  <use href="#c" id="rc" style="fill:red"
       aria-describedby="c rc">
    <title>Warning!</title>
    <desc>colored red</desc>
  </use>

The use element would have the accessible name "Warning!" (and would therefore be identified as a "Warning! image" or "Warning! symbol") and would have the accessible description "A 1cm-radius circle colored red". The original circle and the defs element, which are never directly rendered, would not be exposed in the accessibility tree.

An alternative approach would be to make the implicit labelling/description relationship between the use element and its source graphic be in addition to any labels or descriptions specified for the instance. If that approach were chosen, a decision would need to be made about the appropriate order in which to concatenate the two values: specific first, then general, or general then specific (as in the example)?

Alternatively, if the re-used graphic is represented as a cloned subtree, as proposed in a note to the use element role mapping, the cloned circle, including its name and description, would be accessible as a child element of the use.

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 Relations accessibility API computational requirements in [[!CORE-AAM]].

The CORE-AAM section on Relations requires that assistive technologies SHOULD provide a method to navigate to (and within) structured content referenced by aria-describedby. This would be difficult to implement with the current approach of not including non-rendered descriptive content in the accessibility tree.

Group Position

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

SVG Views

SVG provides authors with the means of specifying a particular view of the document. A view is applied through the target fragment of the document URL, either by referencing the id of a view element, or by specifying a custom view using the SVG view specification fragment identifier.

The visual effect of an SVG view is equivalent to modifying attributes on the parent svg element (for a view element) or the root element (for an SVG view specification fragment). User agents SHOULD therefore modify the accessible object representing that svg when a view is in effect.

In particular, the following changes should be made:

A navigation action towards a URL including an SVG view specification or the id of a view element SHOULD be treated as a series of property change events on the target svg element followed by navigation to that element. User agents MAY represent the property changes as the deletion of existing nodes followed by the insertion of modified nodes.

SVG Views provide a functionality unique to SVG, with no direct equivalent in HTML documents. They may be used as the end-point of a navigation action, but are not themeselves a container for the targetted content. They may also be used at the time an SVG document is embedded, to subset the visual content to only include a portion of the file.

The editors would be very interested in practical examples of SVG views in use, so that we may determine if the above requirements are sufficient. Particular issues to consider include whether special rules are required for managing keyboard focus, or for excluding content that is rendered offscreen when a view is in effect.

The editors will also be examining existing behavior of user agent/assistive technology combinations when browsing SVG documents with views, and will be proposing author best practices accordingly.

In addition, there have been proposals to deprecate the viewTarget attribute, and the corresponding parameter for SVG view fragments, in SVG 2. Their intended use, to trigger visual styling changes in the target element, has never been well implemented by user agents. Without viewTarget, there would be no native way in SVG to indicate the semantic target of a given view. For view elements (but not view fragments), a possible alternative is to encourage authors to directly specify aria-flowsto attributes. These would then need to be mapped to the relevant svg element.

This raises the question of whether any other (or all) ARIA attributes should be mapped from the view element onto the accessible object for the svg element while the view is in effect. This would require careful consideration of all possible consequences and conflicts. For example, should a view be able to change the role of the SVG element?

Declarative Animation

SVG animation elements may modify element attributes and style properties. CSS animations may modify style properties. Either type of animation may be triggered by user interaction, or may run on a fixed schedule.

If an animated change affects whether an element is rendered, or change whether it is visible in a way that would cause it to be excluded from the accessibility tree, user agents SHOULD expose the change according to the guidelines in the Changes to document content or node visibility section of the Core Accessibility API Mappings [[!CORE-AAM]].

The SVG 2 specification does not currently define whether WAI-ARIA states and properties are animatable (in other words, whether they can be temporarily modified by declarative animation). Without support for updating ARIA states, it is very difficult to implement an interactive animation in a way that it accessible to assistive technologies.

The editors of this document intend to update the SVG specifications such that states and properties are animatable. In most cases, the animation would be applied as a discrete transition between values. User agents would be expected to expose such an animated change to accessibility APIs in the same way as a scripted change to the same attribute.

The role attribute is not animatable.

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.

Special Document Handling Procedures

SVG user agents MUST conform to the Special Document Handling Procedures in [[!CORE-AAM]].

Appendices

References

Placeholder for references

Acknowledgments

The following people contributed to the development of this document.

Participants active in the SVG Accessibility Task Force active at the time of publication

  • Amelia Bellamy-Royds
  • Erik Dahlström (Opera)
  • Amy Dai (Oracle Corporation)
  • Fred Esch (IBM Corporation)
  • Cameron McCormack (Mozilla Foundation)
  • Charles Nevile (Yandex)
  • Charu Pandhi (IBM Corporation)
  • Janina Sajka
  • Doug Schepers (W3C)
  • Rich Schwerdtfeger (IBM Corporation)
  • Léonie Watson (The Paciello Group, LLC)
  • Jason White (Educational Testing Service)

Enabling funders

This publication has been funded in part with Federal funds from the U.S. Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR) under contract number ED-OSE-10-C-0067. 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.