Accessible extended descriptions: HTML documents that demonstrate usage scenarios for the aria-details attribute combined with the details (and associated summary) elements.

The source HTML and CSS code for this website is located in this GitHub repository. You may contribute by filing issues, and/or proposing changes.

Note that these examples of HTML documents do not represent authoritative good practices for content production. This is merely braintorming material to support the ongoing discussion regarding accessible extended descriptions for images and other complex information structures (such as HTML tables). Also note that these examples are intentionally poorly-styled (no fancy CSS), in order to put emphasis on structure and semantics. The goal is to express a generic model that provides flexibility in terms of actual aesthetics. Eventually, this research work may lead to a more formal recommendation for content creators / publishers.

The details (and associated summary) elements contain the actual description. The default collapsed / closed state of the details element means that only the summary "label" is visible. The user can choose to expand / open the details element in order to reveal the full description content (which itself may contain a hyperlink to further external content). The process of expanding / collapsing the details element is keyboard-accessible and generally well-supported in modern web browsers.

When the details element is located immediately after the described object (e.g. immediately below an image), the description summary and full content are reached by simply following the linear reading order. This is accessible to both mainstream users (e.g. visually) and users of assistive technologies (e.g. via synthetic speech / screen readers). The aria-details attribute in the described object (e.g. the source image HTML tag / element) references the immediately-following details element, and as such provides additional semantic information in the accessibility tree that assistive technologies (such as screen readers) rely on to help users navigate content.

When the details element is located away from the described object (e.g. at the end of the HTML document, in the form of a "footnote" ), simply following the linear reading order is not an adequate user experience. Instead, there must be a link to allow the user to jump from the described object into the description, and there must be a "link back" mechanism in order to resume reading from the described object. Because the aria-details attribute is only exposed to users of assistive technologies, there must be an additional "fallback" affordance (such as a regular HTML link) located near the described object. Although such link needs to be visible to mainstream users, it may be styled discretely to avoid cluttering the information stream. Note that in the case of HTML tables which are typically content-rich, it may be preferable to include a description link immediately before the table, rather than immediately after it. Otherwise, users would be forced to skip the entire table (rows and columns) in order to reach the description link.

Note that the use of figure and figcaption to wrap images is entirely optional. In some cases, the alt attribute on the img HTML element is sufficient.

[REMOVED] (only the "visually offscren" technique is recommended, not 'aria-hidden') It is also possible to use the aria-hidden attribute in order to make some content (let's call this "CONTENT A") inaccessible by screen readers and other assistive technologies. This can be used in conjunction with an "offscreen" CSS class which defines styling to visually hide content from view (let's call this "CONTENT B") whilst maintaining keyboard focusability. This way, "CONTENT A" and "CONTENT B" become mutually-exclusive depending on whether the user relies on assistive technology.

It is also possible to use an "offscreen" CSS class which defines styling to visually hide content from view whilst maintaining keyboard focusability, and ensuring accessibility via assistive technologies such as screen readers.