View source for Using aria-describedby to provide descriptions of images

[[Category: Techniques]]
[[Category: ARIA Techniques]]
[[Category: Techniques Ready For Review]]

== Status ==

* [https://www.w3.org/2002/09/wbs/35422/htmltfJun182012/results#xlabel3 Surveyed by TF 25 June 2012]
* [http://www.w3.org/2012/06/25-html-techs-tf-minutes Discussed by TF 25 June 2012]
* Reopening to address Laura Carlson's comment, surveyed in [https://www.w3.org/2002/09/wbs/35422/WCAG_Aug20_2013/results#x2663  Responses to Public Comments, ARIA Techniques and review of images section of WAI tutorials. August 20th 2013]
* Discussed [http://www.w3.org/2013/10/08-wai-wcag-minutes.html#item05 October 8] and this technique updated to adhere with response to Laura Carlson's comment [https://www.w3.org/2006/02/lc-comments-tracker/35422/NOTE-WCAG20-TECHS-20130905/2848 LC-2848] and John Foliot's comment [https://www.w3.org/2006/02/lc-comments-tracker/35422/NOTE-WCAG20-TECHS-20130905/2847 LC-2847]. Will be confirmed on the November 26 survey.
* Added to XML by AWK 2014/1/2

== Using ARIA Describedby to provide descriptions of images==
=== User Agent Notes [To be published separately] ===
Updated by David MacDonald July 16, 2013
*Jaws V.11 and greater has complete support. IE10 JAWS 14. Speaks alt and then "press JAWS key + alt +r to hear descriptive text". IE 10 intermittent support, sometimes works, sometimes need to reload the page for JAWs to read it properly. 
*ChromeVox V.1 and greater has complete support? 
*VoiceOver V.3 and greater supports but replaces ALT text if both are present
*NVDA 2 reads ALT text if both are present but not Describedby unless it is alone
*Window Eyes as of V.7 ???.

=== Applicability ===
As of this writing this technique applies to HTML technologies. 

This technique relates to:

* [http://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html Success Criterion 1.1.1 (Text Alternatives)]

===Description===

The objective of this technique is to provide descriptions of images when a short text alternative does not adequately convey the function or information provided in the object. 

A feature of WAI-ARIA is the ability to associate descriptive text with a section, drawing, form element, picture, and so on using the <code>aria-describedby</code> property. This is similar to the <code>longdesc</code> attribute in that both are useful for providing additional information to help users understand complex images. Like <code>longdesc</code>, descriptive text provided using <code>aria-describedby</code> is separate from the short name provided using the <code>alt</code> attribute in HTML. Unlike <code>longdesc</code>, <code>aria-describedby</code> cannot reference descriptions outside of the page containing the image. An advantage of providing long descriptions using content from the same page as the image is that the alternative is available to all, including sighted people who do not have assistive technology. It is worth noting that as of the time of writing (October 2013) some assistive technologies read <code>aria-describedby</code> content immediately after an image's alt attribute information without user activation - whereas most implementations of <code>longdesc</code> require the user to take explicit action to read the additional description.

Like <code>aria-labelledby</code>, <code>aria-describedby</code> can accept multiple ids to point to other regions of the page using a space separated list. It is also limited to ids for defining these sets.

===Examples===
====Example 1====
The following example shows how <code>aria-describedby</code> can be applied to an image to provide a long description, where that text description is on the same page as the image. 

<pre>
<img src="ladymacbeth.jpg" alt="Lady MacBeth" aria-describedby="p1">
<p id="p1">This painting dates back to 1730 and is oil on canvas. It was created by 
Jean-Guy Millome, and represents ...</p>
</pre>

===Resources===
* [http://www.w3.org/TR/wai-aria-practices/ WAI ARIA 1.0 Authoring Practices]
* [http://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation HTML to Platform Accessibility APIs Implementation Guide: Accessible Name and Description Calculation]

===Related Techniques===
*[http://www.w3.org/TR/WCAG20-TECHS/xxxxx.html ARIA-XX: Using aria-labelledby to provide labels for objects.]
*[http://www.w3.org/TR/WCAG20-TECHS/xxxxx.html ARIA-XX: Using aria-label to provide labels for objects.]
*[http://www.w3.org/TR/2012/NOTE-WCAG20-TECHS-20120103/G92 G92: Providing long description for non-text content that serves the same purpose and presents the same information]
*[http://www.w3.org/TR/2012/NOTE-WCAG20-TECHS-20120103/H45.html H45: Using longdesc]

===Tests===
====Procedure====
#Examine each image element where a <code>aria-describedby</code> attribute is present.
#Examine whether the <code>aria-describedby</code> attribute  programatically associates an element with its text description, via the <code>id</code> attribute on the element where the text to be used as the description is found. 
#Examine whether the combined text equivalent and associated text description accurately describe or provide the equivalent purpose to the object.

====Expected Results====
Tests #1, #2 and #3 are true.