Assistive technologies need semantic information about the structures and expected behaviors of a document in order to convey appropriate information to persons with disabilities. This specification defines a [[!WAI-ARIA]] module of core roles, states and properties specific to web graphics. These semantics allow an author to express the logical structure of the graphic to assistive technologies. Assitive technologies could then enable semantic navigation and adapt styling and interactive features, to provide an optimal experience for the audience. These features complement the graphics and document structure elements defined by [[HTML5]] and [[SVG2]].
This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.
Please record issues on this specification through the Github W3C/aria issue tracker, using the prefix "Graphics" for any issue.
WAI-ARIA is a technical specification that provides a framework to improve the accessibility and interoperability of web content and applications. It enables web browsers to map the accessibility semantics in web content to platform-specific accessibility APIs. This enables web content to be interoperable with platform assistive technologies, similar to native platform applications, without requiring authors to include platform dependencies.
This specification is a modular extension of WAI-ARIA designed to support graphics. The goals of this specification include:
This specification defines the core roles that would be used in all structured graphics or diagrams. Future work will expand on this framework to enable more detailed annotation of data-rich graphics such as charts or maps.
For a more detailed explanation of WAI-ARIA please refer to the WAI-ARIA Introduction and how it applies to Rich Internet Application Accessibility.
This specification defines a module of WAI-ARIA for graphics, including roles, states, properties and values. It impacts several audiences:
Each conformance requirement indicates the audience to which it applies.
This module builds on the general User Agent support principles defined in [[!WAI-ARIA]] by also providing the ability for user agents to enhance the general user interface presented to readers.
The Graphics WAI-ARIA module follows the model for co-evolution of WAI-ARIA and host languages defined in [[!WAI-ARIA]]. It is intended to augment semantics in supporting languages like [[HTML5]], [[!SVG2]] and EPUB, or to be used as an accessibility enhancement technology in other markup-based languages that do not explicitly include support for ARIA. It clarifies semantics to assistive technologies when authors create new types of objects, via style and script, that are not yet directly supported by the language of the page, because the invention of new types of objects is faster than standardized support for them appears in web languages.
It is not appropriate to create objects with style and script when the host language provides a semantic element for that type of objects. While WAI-ARIA can improve the accessibility of these objects, accessibility is best provided by allowing the user agent to handle the object natively. For example, it is not better to use a div element than it is to use a native heading element, such as an h1.
It is expected that, over time, host languages will evolve to provide semantics for objects that currently can only be declared with this specification. This is natural and desirable, as one goal of WAI-ARIA is to help stimulate the emergence of more semantic and accessible markup. When native semantics for a given feature become available, it is appropriate for authors to use the native feature and stop using this module for that feature. Legacy content may continue to use the Graphics WAI-ARIA module, however, so the need for user agents to support it remains.
While specific features of this module may lose importance over time, the general possibility of the Graphics WAI-ARIA module to add semantics to web graphics or open web based standards, is expected to be a persistent need. Host languages may not implement all the semantics this module provides, and various host languages may implement different subsets of the features. New types of objects are continually being developed, and one goal of this specification is to provide a way to make such objects accessible, because authoring practices often advance faster than host language standards. In this way, this module and host languages both evolve together but at different rates.
Some host languages exist to create semantics for features other than the user interface. For example, SVG expresses the semantics behind production of graphical objects, not of user interface components that those objects may represent. Host languages such as these might, by design, not provide native semantics that map to this specification's features. In these cases, the Graphics WAI-ARIA module could be adopted as a long-term approach to add semantic information to these host languages.
Programmatic access to accessibility semantics is essential for assistive technologies. For more information, refer to the Assistive Technologies section in [[!WAI-ARIA]].
This specification indicates whether a section is normative or informative. Classifying a section as normative or informative 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 authors, user agents and assistive technologies MUST follow for an implementation to conform to 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.
This section defines additions to the WAI-ARIA role taxonomy and describes the characteristics and properties of all roles. See ARIA Roles for descriptions of the fields provided by this module.
Authors are given the ability to influence what is presented
to assistive technologies and to influence navigation through
the use of roles and properties. With graphics, there are many
cases where presenting and navigating every element will make the
graphic harder to understand and use.
Authors may mark elements for exclusion
from the semantic representation of the document
(the accessibility tree) by assigning
the role
In addition, certain roles,
such as
A role of none should never be used
for interactive elements or those with WAI-ARIA states and properties.
Below is an alphabetical list of the WAI-ARIA roles defined in this specification. They would normally be used in combination with other roles defined in [[WAI-ARIA]] to annotate graphics within documents and rich internet applications.
Placeholder for compact list of roles
A type of
Similar to other graphics-doc role applies to the root element of
a region of the page containing related information,
where the user's primary interaction mode is expected to be
browsing the document rather than controlling an application.
The element with this role
may be the root element of the document file,
or of a nested structure within it.
The graphics-doc may be distinguished
from similar roles as follows:
Relative to other documents, a graphics-doc
is distinguished by the semantic importance of its
visual (usually two-dimensional) representation.
User agents and assistive technologies
SHOULD take this into consideration
when supporting navigation of the graphic.
Accessibility technologies that re-format or re-style a document
SHOULD NOT alter the layout of a graphics-doc
except in ways that are consistent
with the semantic roles and relationships of its content.
Relative to an graphics-doc
is distinguished by the structured nature of its content.
Its child elements may have semantic meaning,
and may include links or other interactive widgets.
Relative to a graphics-doc is self-contained.
Its meaning persists when separated from surrounding content.
The element with the graphics-doc role defines
the scope and context for interpretation of the child content.
In general, authors SHOULD use the graphics-doc role
for structured graphics such as
charts, maps, diagrams, technical drawing, blue prints and instructional graphics.
However, if a single large graphic has discrete regions
that may be safely re-arranged without sacrificing meaning,
each of those regions SHOULD be a distinct graphics-doc.
An alternative role (such as graphics-doc may also be nested inside another,
for example a bar chart that is embedded in a map
or a matrix of chart panels
should have a role of graphics-doc.
The nested document provides encapsulation;
navigation between components of
the inner and outer graphics should be explicit.
To support user agents and assistive technologies
based on the ARIA 1.0 specification,
authors may wish to include the role="graphics-doc document".
Future specifications may define more specific roles
for particular types of graphical documents with
special semantic structures. Those more specific roles
would be subclasses of graphics-doc.
<!-- An SVG diagram of an electrical circuit -->
<svg xmlns="http://www.w3.org/2000/svg"
width="400" height="200" viewBox="0 0 200 100"
role="graphics-doc document" >
<title>A simple circuit</title>
<desc>A circuit with one source, one switch, and one load</desc>
<style type="text/css">
/* omitted */
</style>
<g id="battery-1" role="graphics-symbol img"
aria-roledescription="source"
aria-label="battery"
aria-flowto="switch-1"
transform="translate(20,50)" >
<path d="M-15,-5 h30 M-5,5 h10" />
</g>
<path class="wire" d="M20,45 V20 H90"/>
<g id="switch-1" role="graphics-symbol img"
aria-roledescription="switch"
aria-label="single-pole switch"
aria-flowto="lightbulb-1" >
<path d="M90,20 L105,30" />
<circle class="connection" cx="90" cy="20" r="2" />
<circle class="connection" cx="110" cy="20" r="2" />
</g>
<!-- more wires and a light bulb -->
</svg>
| Characteristic | Value |
|---|---|
| Is Abstract: | |
| Superclass Role: | |
| Subclass Roles: | |
| Base Concept: | |
| Related Concepts: |
|
| Required Context Role: | |
| Required Owned Elements: | |
| Required States and Properties: | |
| Supported States and Properties: | |
| Inherited States and Properties: | |
| Name From: | author |
| Accessible Name Required: | True |
| Inherits Name Required: | |
| Children Presentational: | False |
| Inherits Presentational: | |
| Implicit Value for Role: |
A section of a
Container elements that instead represent a collection
of disconnected objects should instead be given the
Unlike a graphics-object need not be self-contained,
and it does not establish a new context for navigation.
However, user agents and assistive technologies
SHOULD provide a way for users, particularly non-visual users,
to navigate the nested structure of objects
in a hierarchical manner, similar to nested lists.
To support user agents and assistive technologies
based on the ARIA 1.0 specification,
authors may wish to include the role="graphics-object group".
The code that follows is a portion of the markup for a
structured graphic. It includes SVG g grouping
elements with various roles:
graphics-object for distinct objects,
such as the house, its door, or roof.Where a graphical object has multiple sub-components, the group role is provided as an explicit fallback.
<svg xmlns="http://www.w3.org/2000/svg"
width="600" height="400" viewBox="0 0 600 400"
role="graphics-doc document" xml:lang="en">
<title>Home</title>
<g role="img" aria-label="background">
<desc>Blue sky, sunshine, and green grass</desc>
<!-- The multiple parts of the background form a single image
conveyed by that one description. -->
<rect fill="lightSkyBlue" height="100%" width="100%" />
<circle fill="yellow" stroke="gold" stroke-width="4"
cx="0" cy="0" r="50" />
<path fill="none" stroke="gold" stroke-width="3"
d="..." />
<rect fill="#6a2" y="300" width="100%" height="100" />
</g>
<g role="graphics-object group"
aria-labelledby="house-label"
transform="translate(100,325)">
<desc>A two-storey brick house, drawn with basic shapes.
</desc>
<!-- The house has a number of details worth calling out,
so it is a graphical object -->
<rect fill="firebrick" stroke="darkRed"
width="300" height="200" y="-200"
role="none" /><!-- the walls of the house are
already described thoroughly,
so no role is required -->
<g role="graphics-object" aria-label="door"
transform="translate(30,-90)">
<desc>The brown door on the left side of the building
has a window and a round doorknob</desc>
<!-- The graphical object role allows for further
nested sub-components.
However, based on the default SVG API mappings,
these shapes, which have neither labels nor descriptions,
will be treated as presentation. -->
<rect fill="darkKhaki" stroke="#632"
width="50" height="90"/>
<rect fill="lightSteelBlue" stroke="#632" stroke-width="4"
x="5" y="5" width="40" height="30" />
<circle fill="gray" stroke="#444" stroke-width="0.7"
cx="10" cy="50" r="4" />
</g>
<g role="group" aria-label="windows"
fill="lightSteelBlue" stroke="#632" stroke-width="6">
<!-- The windows are distinct objects,
grouped together with a common label -->
<g role="none" transform="translate(0,-85)">
<rect aria-label="first-floor window"
x="100" width="25" height="45">
<desc>A small window beside the door</desc>
</rect>
<path aria-label="first-floor living-room window"
d="M180,0h100v60h-100v-60z
m30,0v60 m40,0v-60">
<desc>A large three-pane window fills
the rest of the first floor</desc>
</path>
</g>
<g role="none" transform="translate(0,-180)">
<!-- more windows on the second floor -->
</g>
</g>
<!-- more markup for the roof and chimney -->
<text id="house-label"
font-family="cursive" font-size="36px"
x="70" y="50">My House</text>
</g>
<!-- more markup for the trees -->
</svg>
| Characteristic | Value |
|---|---|
| Is Abstract: | |
| Superclass Role: | |
| Subclass Roles: | |
| Base Concept: | |
| Related Concepts: |
|
| Required Context Role: | |
| Required Owned Elements: | |
| Required States and Properties: | |
| Supported States and Properties: | |
| Inherited States and Properties: | |
| Name From: |
|
| Accessible Name Required: | False |
| Inherits Name Required: | |
| Children Presentational: | False |
| Inherits Presentational: | |
| Implicit Value for Role: |
A graphical object used to convey a simple meaning or category, where the meaning is more important than the particular visual appearance. It may be a component of a larger structured graphic such as a chart or map. The symbol itself is an atomic object; children are presentational.
When used as part of a structured symbolic language,
the
To support user agents and assistive technologies
based on the ARIA 1.0 specification,
authors may wish to include the role="graphics-symbol img",
if that is not already the default semantic role for the element.
<!-- Within an HTML document listing a restaurant menu -->
<h2>Appetizers</h2>
<ul>
<li> Spinach Salad with Strawberry & Almonds
<img role="graphics-symbol" title="Vegetarian" src="../assets/leaf.svg" />
<img role="graphics-symbol" title="Contains Nuts" src="../assets/peanut.svg" />
</li>
<li> Chicken Satay with Peanut Sauce
<img role="graphics-symbol" title="Contains Nuts" src="../assets/peanut.svg" />
</li>
<!-- … -->
</ul>
<!-- Within an SVG diagram of an electrical circuit -->
<g id="lightbulb-1" role="graphics-symbol img"
aria-roledescription="load"
aria-label="lightbulb"
aria-describedby="lightbulb-1-label"
aria-flowto="battery-1"
transform="translate(180,50)">
<text id="lightbulb-1-label"
x="-15" dy="0.5ex" text-anchor="end" >10W</text>
<circle r="10" />
<path d="M0,-10 C0,8 5,8 5,0 C5,-8 0,-8 0,10" />
</g>
<!-- Within an architectural blueprint-style SVG diagram -->
<g role="graphics-symbol img">
<title>Door</title>
<desc>on West side of South wall</desc>
<line stroke-width="8" stroke="white"
x1="50" y1="275" x2="150" y2="275"/>
<line stroke-width="4" stroke="#444"
x1="50" y1="275" x2="125" y2="225"/>
</g>
<!-- … -->
<use xlink:href="#outlet" role="graphics-symbol img"
x="5" y="130" width="40" height="40">
<title>Electrical outlet</title>
<desc>at center of West wall</desc>
</use>
| Characteristic | Value |
|---|---|
| Is Abstract: | |
| Superclass Role: | |
| Subclass Roles: | |
| Base Concept: | |
| Related Concepts: | symbol |
| Required Context Role: | |
| Required Owned Elements: | |
| Required States and Properties: | |
| Supported States and Properties: | |
| Inherited States and Properties: | |
| Name From: | author |
| Accessible Name Required: | True |
| Inherits Name Required: | |
| Children Presentational: | True |
| Inherits Presentational: | |
| Implicit Value for Role: |
The following core ARIA roles, defined in [[WAI-ARIA]], are also relevant for annotating graphics:
The following examples demonstrate appropriate use of
Within an HTML 5 document, an inline SVG
may sometimes represent an atomic img.
If the graphics form part of the natural reading flow
of the text, then this role is sufficient, as in the first example:
<p>A repeating SVG gradient is defined using the
<code>spreadMethod</code> attribute.
A value of <code>repeat</code> causes the color stops
to repeat in the same order, from beginning to end:</p>
<svg class="inline-example" role="img">
<title>A repeating linear gradient</title>
<desc>The gradient starts dark, slowly shifting to light,
then quickly dark again. This pattern repeats four
times left to right, each time brightening across a large
region and then getting dark within a short space.
</desc>
<linearGradient id="repeat" x2="25%" spreadMethod="repeat">
<stop offset="0" stop-color="black" />
<stop offset="0.8" stop-color="white" />
<stop offset="1" stop-color="black" />
</linearGradient>
<rect width="100%" height="100%" fill="url(#repeat)" />
</svg>
The following example provides the same content, but now structured as a figure that may be re-positioned separately from the flow of paragraph text.
<figure id="fig1" role="figure region">
<svg id="fig1A" class="nested-figure" role="figure"
aria-labelledby="fig1-caption, fig1A-caption">
<!-- markup omitted-->
</svg>
<svg id="fig1B" class="nested-figure" role="figure"
aria-labelledby="fig1-caption, fig1B-caption">
<linearGradient id="reflect" spreadMethod="reflect"
xlink:href="#repeat" />
<text id="fig1B-caption" class="caption" dy="1em"
>b) spreadMethod="reflect"</text>
<rect role="img"
y="25%" width="100%" height="75%" fill="url(#reflect)" >
<title>A reflecting linear gradient</title>
<desc>The gradient again starts dark, slowly shifting to light,
then quickly dark again. However, the next repeat shifts
quickly to the light, then slowly back dark.
The original pattern is then repeated, followed by the reflected
version again.
</desc>
</rect>
</svg>
<figcaption id="fig1-caption"
>Figure 1: Repeating SVG gradients</figcaption>
</figure>
Finally, the last version uses a
<figure id="fig1" role="figure region">
<svg role="graphics-doc">
<title>Repeating versus reflecting linear gradients</title>
<desc>
The graphic shows two gradient patterns,
annotated with text labels and arrows.
Both gradients use the same series of color stops,
starting dark, slowly shifting to light,
then quickly dark again.
This cycle covers one-quarter of the width of the graphic,
starting on the left.
The two gradients differ in their repeat cycles.
</desc>
<defs>
<!-- markup omitted -->
</defs>
<g role="graphics-object" aria-labelledby="repeat-label">
<!-- markup omitted -->
</g>
<g role="graphics-object" aria-labelledby="reflect-label">
<desc>
The gradient stretches across the bottom half of
the graphic.
Each cycle of the gradient alternates direction,
left-to-right then right-to-left,
as do the arrows that emphasize the pattern.
</desc>
<rect y="50%" width="100%" height="50%" fill="url(#reflect)" />
</rect>
<use y="70%" xlink:href="#gradient-vector" >
<title>1st cycle</title>
<desc>left-to-right arrow, starting from x="0"</desc>
</use>
<use y="70%" x="-50%" transform="scale(-1,1)"
xlink:href="#gradient-vector" >
<title>2nd cycle, reflected</title>
<desc>right-to-left arrow, ending at x="25%"</desc>
</use>
<use y="70%" x="50%" xlink:href="#gradient-vector" >
<title>3rd cycle</title>
<desc>left-to-right arrow, starting from x="50%"</desc>
</use>
<use y="70%" x="-100%" transform="scale(-1,1)"
xlink:href="#gradient-vector" >
<title>4th cycle, reflected</title>
<desc>right-to-left arrow, ending at x="75%"</desc>
</use>
<text id="reflect-label" class="overlay-text"
aria-label="spreadMethod='reflect'"
dy="-0.2em" dx="-0.2em" x="100%" y="100%"
>reflect</text>
</g>
</svg>
<figcaption>Figure 1: spreadMethod options for
repeating SVG gradients</figcaption>
</figure>
Should we expand on the following example to demonstrate how canvas hit regions create a graphical document?
<!-- Within the fallback DOM dynamically constructed
for an HTML 5 canvas game,
elements may represent the different images
that create the composite graphic -->
<canvas role="graphics-doc">
<p id="scene-desc" role="img"
aria-label="The Dungeon"
aria-describedby="scene-desc">
The door opens into a long hallway.
Every few steps on either side are barred doors.
Moisture drips from the stone walls.
</p>
<p id="grue-1" role="img"
aria-label="Grue"
aria-describedby="grue-1">
An amorphous and poorly defined, but unmistakably sinister,
creature blocks the passage.
</p>
<!-- more DOM elements representing game controls -->
</canvas>
WAI-ARIA provides a collection of accessibility state and properties which are used to support platform accessibility APIs on various operating system platforms. Assistive technologies may access this information through an exposed user agent DOM or through a mapping to the platform accessibility API. When combined with roles, the user agent can supply the assistive technologies with user interface information to convey to the user at any time. Changes in states or properties will result in a notification to assistive technologies, which could alert the user that a change has occurred.
The HTML Working Group has incorporated the WAI-ARIA attributes into HTML 5. Official support for WAI-ARIA in HTML is provided in that specification.
Validation support for the roles defined in this module will be added once the specification reaches recommendation.
For information on incorporating WAI-ARIA into other grammars, refer to Appendix A of [[!WAI-ARIA]]
Review whether any additional schemata are necessary for this module.
A detailed history of changes committed is available from the github repository for this document. When drafts of this document begin to stabilise, human-readable change logs will be incorporated.
The following table provides a quick reference to the supported states and properties for all WAI-ARIA roles that may be used in markup.
In addition to the states and properties shown in the table, the following global states and properties are supported on all roles.
Placeholder for global states and properties
Placeholder for quick reference table
The following people contributed to the development of this document.