Maybe Don’t Use Flow Charts on GitHub

In February the GitHub blog announced users would be able to Include diagrams in your Markdown files with Mermaid. I thought this was nifty, and even noticed on an initial scan that they considered screen reader users. Until I read this (since deleted):

…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.

That was a sign that nobody had done any testing with a screen reader, let alone understood how they worked. I looked at some sample charts and found screen readers announce them as nothing but run-on text. There are no relationships, no structure, nothing to give context to the chart.

I taught myself just enough of the Mermaid syntax to make this decision tree flow chart for a GitHub bug report:

A nested bullet list representing the flow of that chart:

Make Your Own

If you want to make your own flow chart on GitHub, here is the syntax I used:

```mermaid 
  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];
```

This is sloppy logic, of course.

What’s Wrong?

I hit the SVG in JAWS, NVDA, and VoiceOver. The line breaks I added to force wrapping appear in the speech log. The MarkDown ` characters I used to indicate code did not convert, so were announced (as grav). Nodes were not separated by white space, so in many cases were treated as compound words by the screen reader.

Here is the output directly from the speech viewer of JAWS 2021 with Chrome (with ` replaced with grav to reflect how it was announced):

Unlabeled 0NoYesJPG/PNG/GIFNoYes, and it
is lengthyYes, a
brief oneSVGgravnonegravgravtablegravgravgridgravgravpresentationgravgravimagegravNoYes, and
it is lengthyYes, a
brief onegravtreegravNoYesNoYesNoYesNoYesUsing a flow
chart in GitHubMust it be
accessible?Wrong,
try againInto what format
does it render?Does it have
an gravaltgrav?Wrong,
try againManually add
a plain text
description
of the chart.What gravrolegrav
does it have?Wrong,
try againManually add
a plain text
description
of the chart.Does it have
an gravaria-labelgrav?Wrong,
try againManually add
a plain text
description
of the chart.Does it contain
any gravtreeitemgrav
roles for the
text nodes?Wrong,
try againAre they contained
in / owned by gravgroupgrav
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

Some of the reasons this is inaccessible:

• the overall SVG exposes no structure;
• the SVG nodes have no semantic or structural meaning;
• the connectors have no source order position that corresponds to the programmatic connections;
• the nature of the connections is not exposed in text.

WCAG Issues

As it stands, using a chart generated from mermaid-js almost guarantees the following WCAG violations:

• 1.1.1 Non-Text Content, which the current text output fails to address;
• 1.3.2 Meaningful Sequence, as I note with the node ordering;
• 1.4.3 Contrast (Minimum), and I have made no effort to look for an existing issue,
• 4.1.2 Name, Role, Value, which sets no roles to even assign it an accessible name.

I suspect 1.4.11 Non-Text Contrast, 1.4.12 Text Spacing, and 3.1.2 Language of Parts are at risk in some implementations as well.

Microsoft tried to address the 1.1.1 issue in a PR for Fluid, but it does not describe the content. It is also for a flat structure. For comparison, when I created the SVG above and tried to give it an appropriate plain text alternative, this was my best effort:

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

This is obviously way too cumbersome and lacks the necessary structure.

What to Do?

The good news is that this launch raised the profile of Mermaid enough for accessibility practitioners to notice it and file issues. Some work has started, but it is a long way from done.

For now, if you cannot include a plain text description of the flow chart in the same comment as the graphic, don’t use it. It is too broken for now.

References

GitHub issues:

• More Accessible Mermaid Charts #2732, 15 February 2022.
• Accessibility: Screen readers doesn’t announce any information on the connected nodes or direction of connection #2395, 11 October 2021.
• Accessibility: Screen readers doesn’t announce any information on the connected nodes or direction of connection #1013, 18 October 2019; closed, locked, and conversation limited by project maintainers on Apr 28, 2021 due to no activity from project maintainers.

Some reference material for working on making SVGs more accessible in general:

• 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.

Update: 21 April 2022

While More Accessible Mermaid Charts #2732 has been closed thanks to merged PRs to add accessible names and descriptions to the SVG output, the Mermaid live editor does not appear to support them yet. The reading order and connections in flow charts appear to still be broken. Here is the Mermaid live editor with my flow chart, new attributes commented out. Try it yourself.

The code I added, per the PRs:

  title Decision tree
  accDescripton Guidelines for choosing the appropriate image format and accessibility affordances.

Update: 9 May 2022

The issue More Accessible Mermaid Charts #2732 was re-opened (and have since closed) to address an issue found in regression testing. The use of title was a problem because the word “title” could also appear in node text.

The maintainers adjusted the parser to look for accName instead, and also updated accDescription to accDesc, both of which match my original suggestion (so blame me). When this rolls out to the live editor, you can use this construct instead of what I show in the previous update:

  accName Decision tree
  accDesc Guidelines for choosing the appropriate image format and accessibility affordances.

The accessible description will now also accept a multi-line description, but I am not sure if that is a good idea or not (since it is all concatenated when announced by a screen reader).