More Accessible Mermaid Charts

👋 it would be nice to work towards more accessible features now that this library is in much wider use. I think a couple of low hanging fruit items would be to include <title> elements in the output svg and <description> so that people creating charts can offer text explanations of the charts.

There is lots of other work too be done in this area, but this seems like a simple place to start.

Charts to be completed:

• Pie Chart PR
• Flowchart PR
• Sequence diagram PR
• Class Diagram PR
• State Diagram PR
• Entity Relationship Diagram PR
• User Journey PR
• Gantt PR
• Requirement Diagram PR

UPDATE 2-22-2022 (Twosday):

Ok I have a pr open with a new accessibility function that can add a title and a description to a chart. I set it up for Pie charts as they already had a title.

I am probably a blocker on this issue since I have been dealing with a bunch of family things and do not want to prevent someone else from picking this up. Feel free to either merge my pr and then add other charts or start work in some other way. If you would like to merge my pr and something needs to be cleaned up I will happily do it. cc @knsv

[aardrian]

I want to add some more context to this issue.

Using the following flow chart:

  flowchart TD;
      A[Using a flow<br>chart in GitHub] --> B{Must it be<br>accessible?};
      B -- No --> C[Wrong,<br>try again];
      B -- Yes --> D{Into what format<br>does it render?};
      D -- JPG/PNG/GIF --> E{Does it have<br>an `alt`?};
      E -- No --> V[Wrong,<br>try again];
      E -- Yes, and it<br>is lengthy --> V[Wrong,<br>try again];
      E -- Yes, a<br>brief one --> F[Manually add<br>a plain text<br>description<br>of the chart.];
      D -- SVG --> G{What `role`<br>does it have?};
      G -- `none` --> N[Wrong,<br>try again];
      G -- `table` --> N[Wrong,<br>try again];
      G -- `grid` --> N[Wrong,<br>try again];
      G -- `presentation` --> Y[Manually add<br>a plain text<br>description<br>of the chart.];
      G -- `image` --> H{Does it have<br>an `aria-label`?};
      H -- No --> P[Wrong,<br>try again];
      H -- Yes, and<br>it is lengthy --> P[Wrong,<br>try again];
      H -- Yes, a<br>brief one --> Z[Manually add<br>a plain text<br>description<br>of the chart.];
      G -- `tree` --> I{Does it contain<br>any `treeitem`<br>roles for the<br>text nodes?};
      I -- No --> R[Wrong,<br>try again];
      I -- Yes --> J{Are they contained<br>in / owned by `group`<br>roles beyond the<br>first level?};
      J -- No --> S[Wrong,<br>try again];
      J -- Yes --> K{Have you<br>tested in<br>any screen<br>reader?};
      K -- No --> T[Wrong,<br>try again];
      K -- Yes --> L{Did it accurately<br>convey relationships<br>and structure from<br>the chart?};
      L -- No --> U[Wrong,<br>try again];
      L -- Yes --> M[You should write a<br>CSUN talk about it];

Screen readers announce it as nothing but unordered run-on text. There are no relationships, no structure, nothing to give context to the chart. It lacks necessary roles and properties as well.

Here is the output directly from the speech viewer of JAWS 2021 with Chrome (the line breaks are from the <br> elements in the text):

Unlabeled 0NoYesJPG/PNG/GIFNoYes, and it is lengthyYes, a brief oneSVGnone``table``grid``presentation``imageNoYes, and it is lengthyYes, a brief onetreeNoYesNoYesNoYesNoYesUsing a flow chart in GitHubMust it be accessible?Wrong, try againInto what format does it render?Does it have an alt?Wrong, try againManually add a plain text description of the chart.What role does it have?Wrong, try againManually add a plain text description of the chart.Does it have an aria-label?Wrong, try againManually add a plain text description of the chart.Does it contain any treeitem roles for the text nodes?Wrong, try againAre they contained in / owned by group roles beyond the first level?Wrong, try againHave you tested in any screen reader?Wrong, try againDid it accurately convey relationships and structure from the chart?Wrong, try againYou should write a CSUN talk about it

Here is output from the speech viewer of NVDA 2021.3 with Firefox (same about the line breaks):

No Yes JPG/PNG/GIF No Yes, and it is lengthy Yes, a brief one SVG none table grid presentation image No Yes, and it is lengthy Yes, a brief one tree No Yes No Yes No Yes No Yes Using a flow chart in GitHub Must it be accessible? Wrong, try again Into what format does it render? Does it have an alt? Wrong, try again Manually add a plain text description of the chart. What role does it have? Wrong, try again Manually add a plain text description of the chart. Does it have an aria-label? Wrong, try again Manually add a plain text description of the chart. Does it contain any treeitem roles for the text nodes? Wrong, try again Are they contained in / owned by group roles beyond the first level? Wrong, try again Have you tested in any screen reader? Wrong, try again Did it accurately convey relationships and structure from the chart? Wrong, try again You should write a CSUN talk about it

The announcement is a bit different than what is shown here (every ` announces as “grav”, for example). As you read the preceding text, I am sure you can understand how that conveys nothing of the meaning of the chart.

Separately, the answer options in dark mode (“Yes”, “No”, “JPG/PNG/GIF”, etc) all fail WCAG contrast checks. I did not check outside of dark mode. The Firefox accessibility inspector and dev tools identify these failures readily.

Finally, this sentence from the GitHub announcement reveals a complete misunderstanding of how screen readers parse content (they work fine with JS, but the raw MarkDown is just as meaningless as the text I pasted):

…clients requesting content with embedded Mermaid in a non-JavaScript environment (such as a screen reader or an API request) will see the original Markdown code.

Some reference material for working on making the SVGs more accessible:

• Tips for Creating Accessible SVG by Léonie Watson, 2014.
• Accessible SVGs by Heather Migliorisi, 2016.
• Accessible SVG flowcharts by Léonie Watson, 2018.
• Creating Accessible SVGs by Carie Fisher, 2019.
• Accessible SVGs: Inclusiveness Beyond Patterns by Carie Fisher, 2020.
• Accessible SVGs: Perfect Patterns For Screen Reader Users by Carie Fisher, 2021.

[aardrian]

@bee-san I left a comment.

It is frustrating that the bug report was opened after another bug report covering the same issue was closed due to inactivity from the project maintainers. The person who closed it also locked it from follow-up comments or re-opening.

Bugs don’t stop being bugs because you ignore them. Though it was oddly marked as a feature enhancement instead of a bug.