Diagram items should list their relationships for screen reader users

[heiko-folkerts-msg-david]

Describe the Problem

For a screen reader user the items of a diagram are listed as snippets of text. The relation between these elements is unknown to them. This could be solved by describing a snippet with its relation to other parts of the diagram, e.g. start event: connected to "get coffee cup". To keep the description hidden (sighted users see the arrows) one could use a hidden paragraph with the description and reference it with the aria-describedby attribute as specified in the ARIA authoring practices.

Steps to reproduce

1. Turn on a screen reader e.g. NVDA
2. Let the screen reader read a diagram.
3. The reader reads all elements in their order in the page but the relationships between them are not read.

Expected Behavior

• Elements can be focussed with the keyboard/mouse in a screen reader friendly manner
  • System selection is being used for primary element (readers rely on it)
  • If possible, standard shortcuts (arrow keys, TAB, SHIFT+TAB) navigate the graph (readers rely on it)
  • Example: Starting from a BPMN Task I'm able to inspect outgoing connections and follow them
  • Example: Starting from a root or container element, i.e. a BPMN Process or SubProcess, I am able to select / loop through existing graph starts, i.e. BPMN StartEvents and potentially graph ends, i.e. BPMN EndEvents.
• Screenreader friendly text is serialized with the diagram, extensible in libraries built on top of diagram-js
  • Example: In bpmn-js you may want to serialize the bpmn:Documentation attached to an element so it is being read out along with the element name + type.

---

A good chunk of additional context on A11y compliant diagram navigation is provided here.

---

Required by camunda/camunda-modeler#2588

[nikku]

Thanks for opening this issue. I've marked it as a11y.

Would a simple solution "connected to {XYZ}" be sufficient? I imagine that connections transport semantics that would need to be properly reflected in the description.

[nikku]

See also a11y and SVG.

[heiko-folkerts-msg-david]

Well, if bpmn could render its diagram in a SVG with the arrows described, that would be very helpful.

[heiko-folkerts-msg-david]

Yes something like „start transaction“ connected to „get user name” “get user name” connected to “Ask age” “ask age” connected to “error underage” labeled no … Would help.

[nikku]

Happy to take a contribution that improves the situation. It will be a larger contribution though:

• Elements can be focussed with the keyboard/mouse in a screen reader friendly manner
• Screenreader friendly text is serialized with the diagram, extensible in libraries built on top of diagram-js
  • Example: In bpmn-js you may want to serialize the bpmn:Documentation attached to an element so it is being read out along with the element name + type.

As these few bullet points show a11y and screen reader support are non-trivial topics in the context of diagrams.

[nikku]

Moving this issue to backlog.

[nikku]

Also classifying it as an enhancement. There is nothing broken with our current a11y story, as we did not implement any yet. Hope that makes sense.

[heiko-folkerts-msg-david]

Sure, thats right. Sorry for calssifying it as bug. The feature is urgently needed, since I am working in a project that models the contents of stories with BPMN. So if I can help with a bit of coding, I would try my very best.

[pinussilvestrus]

One another report that this one is a needed improvement: #634

/cc @christian-konrad @MaxTru