Need aria-roledescription on each data view

The next important step in making mermaid accessible is to insert some basic ARIA roles to help manage expectations.

First thing: Mermaid generates a chart or data view. Currently there is no semantic role provided for the view, which is unhelpful for users of assistive tech. Most ARIA attributes do very little unless you provide an appropriate role (or if the HTML element has an implicit role, such as <img> or <h1>). <svg> elements are not automatically mapped to img on all platforms, so the aria attributes currently added are likely to be ignored, at least on some configurations.

In particular, HTML <div> and <span> and SVG <g> are mapped to the “generic” role by default, which does not support naming. Mermaid data views are presented as a <div> with a <svg> inside.

(Edit - correction) SVG maps to the “graphics-document” role by default.

Other choices might have been

• role=“img”
• role=“figure”
• role=“graphics-document”

By my reading of these specs, “graphics-document” indeed appears to be the best fit for a data view today.

A graphics document:

• Conveys meaning through visual appearance or layout.
• Is structured. (unlike img)
• Is self-contained (i.e. meaning is retained when separated from the surrounding content, unlike figure, which requires a context).

Note: Some critical comments have been raised about imagining accessible data representations as “graphics” or “visualisations”. To encourage a presentation-independent mindset for representing data, future versions of ARIA may introduce nomenclature for data that have less of a visual bias, such as “projection” or “DX” (for ‘data experience’). My point here is that while “graphics-document” is the best fitting role available today, this may change.

But ARIA already offers a way to announce an alternative name for any given role: aria-roledescription, which may be used to distinguish one kind of chart/diagram/dataview from another.

Mention of aria-roledescription is typically accompanied by warnings of the “with great power comes great responsibility” type, because misuse of this attribute can be very disorientating. Even so, there is a strong case for it here.

So, back to our mermaid view. Is it a flow chart? a sequence diagram? There are a fixed set of chart types available. We know what they are called. Let’s provide a text cue to assistive tech, so that people have an idea what kind of data view they’ve encountered.

Suggestions (assuming a pie chart, but could be any of the standard set of views): <div class="mermaid" role="graphics-document" aria-roledescription="pie chart" aria-labelledby="idOfSVGTitleElement"> …or… <div class="mermaid"><svg id="diagram" role="graphics-document" aria-roledescription="pie chart">

So, for a pie chart that shows browser statistics, instead of the AT announcing “graphics-document browser statistics” you’ll get “pie chart browser statistics”.

I don’t know enough to express a preference about where best to put these attributes; on the div or on the svg. Either way, the element that gets the role will become a node in the accessibility tree, and it is this node that needs a name.

For interactive views, you would typically put a tab stop on that element, so that it can be focused, and become a target for general keyboard input (so this is where you’d add any fancy keyboard handlers too). I don’t think we are ready for that yet.

If it is the SVG then the title element in the SVG is “automagically” used as the accessible name. This is probably what we want. Otherwise the div can point to the id of the title inside the SVG with aria-labelledby. Some testing will confirm which (if any) is better.

Last point: aria-roledescription should be a translatable, human-readable name. I haven’t looked at mermaid’s i18n features (if any) but the case of other language versions of this string should not be overlooked for non-English content.

[sidharthv96]

If it’s a small fix, we can try to get it in before the 9.3.0 release. We have branched off and released an RC, but might be able to squeeze in small fixes.

[weedySeaDragon]

Glad you are posting this here, @brennanyoung . No apology needed IMNSHO: Sometimes we just don’t learn things until later. (That’s the real world!)

Now that the structure is there in the code, any future adjustments/changes for this should be really easy.

If you think we should go ahead and change the role, just create a new issue and I can do it quickly. I lean towards going ahead and changing it but YMMV.