Mermaid image accessible descriptions

Open
#2,724 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
html, xml
Domain
accessibility

Research direction

Start with the <description> and <shortdescription> handling for mermaid diagrams, and with the sample-article that the issue points to. Read the linked Mermaid accessibility docs to see how title and description are embedded in the SVG. The issue has no decision yet, so a newcomer should first propose which of the three approaches to take; done means a chosen approach, demonstrated on the sample article.

Written by the indexing model from the issue text.

Description

Currently, mermaid diagrams just dump <description> or <shortdescription> into the text (see sample-article for examples).

Mermaid has its own way to add accessible title/description that will be embedded into the SVG produced:
https://mermaid.js.org/config/accessibility.html

So one approach would be for the author to add info there. Potentially, that is the most flexible as an author could provide different descriptions for different subdiagrams. But it would leave the info outside of PreTeXt's easy reach.

Alternatively, we could try to inject PTX authored descriptions into the mermaid source (yuck).

Or, we could try to figure out a way to provide an accessible label for the entire image block. i.e.

<image box>
<mermaid pre/>
<description div/>
</image box>

Where the description is visually hidden but set as the @labeled-by for the image box. Not sure if that would work well with screen readers or not. Would need testing.

Loosely related to https://github.com/PreTeXtBook/pretext/pull/2568

Dominant language
XSLT
Stars
466
Forks
251
Avg merge
4m
Merged PRs (30d)
13

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PreTeXtBook/pretext

All issues in PreTeXtBook/pretext

Similar issues

More Accessibility issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.