SVG Accessibility API Mappings (SVG-AAM) defines how
user agents map
Scalable Vector Graphics (SVG) [SVG2] 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.
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 https://www.w3.org/TR/.
Particularly problematic open issues
are highlighted in this document,
with links to the GitHub discussion.
Comments on these issues would be particularly appreciated.
Relative to the last published working draft (8 September 2016),
the following major changes have been made:
The handling of use element shadow DOM content has changed.
The roles for determining whether an element is hidden have been simplified,
and coordinated with changes to other WAI-ARIA specifications.
In addition, there have been numerous clarifying edits.
This document was published by the SVG Working Group as a Working Draft.
This document is intended to become a W3C Recommendation.
Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other than work in
progress.
This document was produced by
a group
operating under the
W3C Patent Policy.
W3C maintains a public list of any patent
disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual knowledge of a patent
which the individual believes contains
Essential
Claim(s) must disclose the information in accordance with
section
6 of the W3C Patent Policy.
This specification defines how SVG host language elements and content —
with or without WAI-ARIA
roles, states, and properties applied —
map to accessibility APIs.
Sections give guidance on calculating text alternatives,
mapping actions to events,
event processing, special document handling procedures, and error handling.
This introduction provides
some background on why this specification exists,
and how it relates to other WAI-ARIA specifications.
It includes
a general overview of accessibility APIs
and the hierarchy of accessible objects
known as the accessibility tree.
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 (web browser),
which maps elements and attributes
to the platform Accessibility API.
In Scalable Vector Graphics (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 version 1 [SVG1] and version 1.1 [SVG11] of the SVG specifications
included elements for defining accessible names and descriptions
(<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.
There was similarly no guidance on how user agents should make interactive SVG keyboard accessible.
SVG 2 now incorporates keyboard navigation based on the established model 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 the core DOM Standard [DOM],
supporting JavaScript manipulation of the graphic in interactive environments.
Through the use of JavaScript, CSS, and related APIs,
authors can make SVG look and behave as an interactive application,
to produce rich interactive charts and drawings.
To allow the author to express and dynamically update their intended semantics
in both static and interactive graphics,
SVG 2 supports the use of
WAI-ARIA roles, states, and properties.
Authors may include
WAI-ARIA attributes in their markup
and user agents will translate it
to the platform accessibility APIs.
WAI-ARIA enables rich SVG-drawn Internet applications
to have the same accessibility features as
GUI applications installed on their operating system.
In complex static graphics,
WAI-ARIA provides the missing document structure that is provided in HTML by semantic elements.
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:
WAI-ARIA Authoring Practices Guide [ARIA-PRACTICES],
a W3C Working Group Note,
which 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 developers of user agents and assistive technologies.
This guide relies heavily on the
accessibility API mappings
defined in the
Core Accessibility API Mappings
and
Accessible Name and Description
specifications
([CORE-AAM] and [ACCNAME-AAM])
but defines changes in mappings due to features in the SVG host language [SVG2].
Key areas of difference stem from the intrinsic host language semantics of SVG:
The procedure for mapping the DOM tree to the accessibility tree
is designed to simplify that tree
to only include elements with semantic importance.
SVG elements are assigned default roles and properties,
which in many cases are conditional on whether they meet
the criteria for inclusion in the accessibility tree.
Text computation of names and descriptions use the SVG metadata elements.
Implicit ARIA states (such as whether an element is hidden) must be updated
in response to SVG animations.
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 are parallel structures.
Roughly speaking, the accessibility tree is a subset
of the flattened DOM tree,
which is then 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 a DOM element can be omitted from the accessibility tree
without affecting meaning, 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.
2. Normative User Agent Implementation Requirements for SVG §
This specification marks certain sections
as non-normative, also called informative.
The classification applies to the entire section.
All other sections provide normative requirements.
A statement "This section is non-normative"
applies to all its sub-sections, unless otherwise indicated.
In addition, all text boxes labelled "Note" are informative.
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.
Informative sections and notes 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.
Tree of accessible objects that represents the structure of the user interface (UI). Each node in the accessibility tree represents an element in the UI as exposed through the accessibility API; for example, a push button, a check box, or container.
Accessible Description
An accessible description provides additional information, related to an interface element, that complements the accessible name. The accessible description might or might not be visually perceivable.
Accessible Name
The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element. See related accessible description.
A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g., "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.
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.
Attribute
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.
Element
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.
Event
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.
Hidden
Indicates that the element is not visible, perceivable, or interactive to any user. An element is considered hidden if it or any one of its ancestor elements is not rendered or is explicitly hidden.
Informative
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.
Object
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.
Property
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.
Role
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.
Semantics
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.
State
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.
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.
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.
5.1 General rules for exposing WAI-ARIA semantics §
5.1.1 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.
Note
The other factors for excluding elements,
as described in the Core Accessibility API Mappings,
can be summarized 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.
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.
Non-rendered elements may also be used as the templates
for rendered element instances created by a use element,
as described in the section on Use-Element Shadow Trees.
Note
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,
according to the computed value of the visibility property,
nor interactive to pointer users.
according to the pointer-events property.
User agents SHOULD NOT
expose to accessibility APIs
any element that is hidden in this sense,
unless the author explicitly overrides the hiding
by setting the aria-hidden attribute to false.
In the case of container elements (such as g or svg),
the element is not considered hidden
if any of its descendent content is visible
or can receive user events,
regardless of the computed value of visibility on the element itself.
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 MUST be considered visible or interactive
if any elements within its shadow tree are visible or interactive.
(The container or the use element may, however, still be considered presentational if it does not have any other reason to include it in the accessibility tree.)
A shape element with markers is visible or interactive
if any of its markers are visible or interactive.
Note
In HTML and in other CSS-styled documents,
elements made invisible with visibility: hidden
are always hidden elements for accessibility purposes,
equivalent to un-rendered elements (such as those with display: none).
For SVG, this is not always appropriate,
because of the interaction with the pointer-events property.
In many cases, the invisible 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.
An SVG element with a computed value of visibility: hidden
can be interactive to pointer users
for the following values of the
pointer-events property:
painted, for any rendered element except shape or a text where both the fill and stroke properties have a computed value of none
fill
stroke
all
bounding-box
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].
Note
Various other style properties and geometric attributes (of an element itself or an ancestor element) can make an element invisible. For simplicity, flexibility, and performance reasons, these are not considered a hiding method that excludes elements from the accessibility tree.
When using properties other than display or visibility to hide inactive content, authors can use the aria-hidden attribute to indicate that assistive technologies should ignore the element and its descendents.
Editor's note
Previous drafts of this specification also considered the
fill and stroke properties,
when both set to a value of none,
as a valid way to hide an element.
This has been removed as it introduced excessive complexity.
Some SVG elements (e.g., embedded images) are not affected by stroke and fill;
even those that are can be visible without it, because of markers or filter effects.
Furthermore, it could result in identical-looking graphics
(for example: one that used fill: transparent instead of fill: none)
having markedly different accessibility trees.
Note, however, that the fill and stroke properties
may still have an indirect effect on the inclusion of an element,
depending on the value of the pointer-events property.
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
(in GitHub Issue #6)
on alternative ways to represent
this hidden alternative content
in a way consistent with user agent and accessibility API implementations.
5.1.2 Including Elements in the Accessibility Tree §
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 should normally be omitted
from the accessibility tree,
unless the author explicitly provides semantic content.
However, any rendered SVG element may have semantic meaning.
Authors indicate the significance of the element by including
alternative text content or
WAI-ARIA attributes.
This section defines the rules for including
normally-omitted elements in the accessibility tree.
The following graphical and container elements in the SVG namespace
SHOULD NOT be included in the accessibility tree,
except as described in this section:
shape elements
(circle,
ellipse,
line,
path,
polygon,
polyline,
rect)
the use element
the grouping (g) element
the image element
the mesh 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.
For use elements,
the elements and text in their associated shadow tree MUST be processed
as if it was child content of the use element,
following the conditions specified in processing requiring additional computation.
This means that elements from the shadow tree can be included in the accessibility tree
even if the use element itself has a
(default or author-supplied)
role of presentation.
SVG user agents MUST provide
an accessible object in the accessibility tree
for rendered SVG elements that meet any of the following criteria,
unless they are excluded from the accessibility tree per the rules
in Excluding Elements from the Accessibility Tree:
It has at least one direct child
‘title’ element
or
‘desc' element that is not empty after trimming whitespace. User agents MAY include elements with these child elements without checking for valid text content.
It has an
‘aria-labelledby’ attribute
or
‘aria-describedby’ attribute containing valid IDREF tokens. User agents MAY include elements with these attributes without checking for validity.
Elements that are focusable, or have an ID attribute and an ancestor with the aria-activedescendant attribute that matches the implicit or explicit semantics of the required context role. In either case, the element may receive focus and need to fire a FOCUS event.
Elements that have a mappable role in the role attribute string (see Role Mapping).
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.
Specifically, for SVG the following elements are interactive
and MUST be included in the accessibility tree, without exception,
regardless of whether they would otherwise be considered hidden or presentational:
A rendered element
(or instance of an element in a use-element shadow tree)
with a positive integer value
for the tabindex attribute,
or which is focusable by default
and has not been removed from the tab order with a negative integer tabindex attribute,
which may receive keyboard focus and therefore keyboard input events.
A rendered element
(or instance of an element)
that currently has keyboard focus
(e.g., after being focused from a script),
which may receive keyboard input events.
With regards to pointer events, which bubble up the DOM tree,
the exact element that receives the event may not have semantic meaning
(that is, it may still be presentational).
However, the ability to receive pointer events overrides any exclusion
based on the visibility: hidden style property.
Note
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.
5.2 Conflicts between native markup semantics and WAI-ARIA §
Elements for which no accessible object is created and no role may be applied,
as defined in
the SVG Element Mapping Table,
have no implicit role semantics.
The ‘aria-roledescription’ attribute
MUST NOT be exposed on these elements.
All other SVG elements have implicit role semantics
when used with global WAI-ARIA attributes,
including ‘aria-roledescription’.
5.3 Exposing attributes that do not directly map to accessibility API properties §
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.
SVG user agents MUST conform to the Role Mapping General Rules accessibility API computational requirements in the Core Accessibility API Mappings [CORE-AAM].
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
link role
if the element has a valid href or xlink:href attribute.
For a elements that are not links, use the mapping for
tspan if the a element is a descendent of text,
or the mapping for g otherwise.
A symbol element is not directly rendered,
and therefore not directly exposed in the accessibility tree.
However, the role (default or author-supplied) for the element
will be used for the rendered instance of the symbol
in the use-element shadow tree.
Either the symbol or the use element,
or both,
may have an associated accessible object,
depending on where the author has provided names, descriptions, roles, or interactivity.
The platform mappings given above are similar to
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.
Note that the re-used graphics
in the use element's shadow tree
may still be included in the accessibility tree,
even if the host element is not.
Editor's note
Previous drafts of this specification did not require that
the re-used graphical elements
be exposed directly;
The use element was treated as an atomic object.
This was not consistent with the potential for interactive content or text
within the re-used graphics.
Corresponding with the change to directly expose re-used graphics,
special rules for the accessible name and description of use elements
are no longer required.
The use of the group role for
textPath
and tspan
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).
ARIA 1.1 does not have any roles for non-interactive spans of text.
More work is required to address whether
text-specific platform accessibility API roles
can more effectively serve this function.
In particular, for ATK, the ATK_ROLE_STATIC role
is probably more appropriate than the usual mappings for group.
Suggestions for improved mappings would be welcome,
in GitHub Issue #2)
This section describes how to expose WAI-ARIA states and properties. SVG user agents MUST conform to the State and Property Mapping accessibility API computational requirements in the Core Accessibility API Mappings [CORE-AAM].
In addition, the following attributes on SVG elements
require special processing:
viewTarget
on a view element
creates an aria-flowto relationship
on the associated svg element when the view is active,
as defined in the SVG views section.
xlink:title
on a link element
affects the accessible Name and Description computation.
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 [SVG2],
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.
8. Special Processing Requiring Additional Computation §
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 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.
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.
Otherwise, if the current node is a link,
and it has an xlink:title attribute that was not used for the accessible name,
return the value of that attribute.
When determining whether an element has a direct child element,
only actual DOM child elements are considered,
regardless of whether or not the parent element has an associated shadow tree.
Note
The net effect of these changes is to establish the following priority
of alternative text values for the accessible name:
aria-labelledby
aria-label
a direct child title element
xlink:title attribute on a link
for text container elements,
the text content
The alternative text values for the accessible description
have the following priority:
aria-describedby
a direct child desc element
for text container elements,
the text content
a direct child title element
that provides a tooltip,
when ARIA label attributes are used
to provide the accessible name
xlink:title attribute on a link,
if not used to provide the 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.
SVG user agents MUST conform to the
Relations
accessibility API computational requirements in the Core Accessibility API Mappings [CORE-AAM].
Issue
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 conflicts with the current approach of not including
non-rendered descriptive content in the accessibility tree.
SVG user agents MUST process the element instances
generated for the use-element shadow tree
as if those elements were children of the use element itself,
with the following conditions:
When processing WAI-ARIA attributes on elements within a shadow tree,
the user agent MUST first attempt to match any IDREF values against other elements in the same shadow tree,
before searching for a match in the host's node tree.
If shadow trees are nested,
the user agent MUST recursively search from the current shadow tree
to the tree containing its host use element,
until the document tree is reached.
In all other cases, when matching IDREF values in WAI-ARIA attributes,
the user agent MUST NOT consider elements in the shadow tree
of a use element.
The editors will be working to harmonize these guidelines
with general rules for WAI-ARIA processing of shadow tree elements,
such as in web components.
Feedback from implementers is requested
on the practical feasibility of encapsulating IDREF matching in this manner.
General feedback on shadow DOM and ARIA should be discussed
in the Core-AAM issue.
Feedback unique to SVG can be submitted
to Issue #7 on this specification.
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:
If the view includes a viewTarget attribute,
the svg element SHOULD be mapped
as if it had an aria-flowto attribute
specifying the same list of IDREF values
contained in the viewTarget attribute.
If the view is applied using a view element,
compute the accessible name and description for that element,
ignoring the fact that a view element is excluded from the accessibility tree.
If the result is a non-empty string, it SHOULD replace
the corresponding name or description for the svg element while the view is in effect.
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.
In addition,
the viewTarget attribute,
and the corresponding parameter for SVG view fragments,
has been deprecated 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?
The aria-flowsto attribute is not well supported in assistive tools;
there have been proposals to deprecate it in a future version.
Are there other ways in which user agents could expose the changed view,
so that users of assistive technologies can quickly understand
which parts of the graphic are visible?
Feedback on any of these points can be provided
on issue #8.
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 animation changes the effective value of a WAI-ARIA state or property attribute,
or an SVG attribute that is described in the State and Property Mapping section,
the User Agent MUST expose the change
in the same way as if the actual attribute value was changed.
Note
The role attribute is not animatable.
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].
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.
Implementation of this specification is not expected to add
any new security or privacy considerations to the web platform,
relative to implementation of SVG ([SVG2]) and WAI-ARIA ([WAI-ARIA]) separately.
Editor's note
If you believe there is a potential new security or privacy risk
created by this specification,
please raise an issue
in the specification's GitHub repository.
In addition to the credited authors and editors,
the participants in the SVG Accessibility Task Force
contributed to the development of this document.
Appreciation also goes to Joanmarie Diggs and other implementers
who have offered feedback on the drafts and helped with testing.
A.1.1 Past participants in the SVG Accessibility Task Force §
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.