mgifford/accessibility-skills/mermaid

Mermaid Diagrams Accessibility Skill

Canonical source: examples/MERMAID_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when authoring, generating, or reviewing Mermaid diagrams. Only load this skill if the project uses Mermaid diagrams.

Core Mandate

Accessible Mermaid content depends on four layers: (1) the diagram source and its accessibility metadata, (2) the exact Mermaid renderer and configuration, (3) the generated SVG/raster output, and (4) how the publishing platform embeds and exposes that output. A generated Mermaid diagram is non-text content unless the rendered nodes/relationships are proven to have useful semantics — test the final published output, not just the source or an editor preview.

Before authoring, decide whether a diagram is even needed — a heading, short list, table, or few sentences may communicate the information more clearly. Mermaid is useful when relationships, sequence, branching, hierarchy, timing, or spatial grouping materially improve understanding.

Severity Scale (this skill)

Critical: Use the Correct accTitle/accDescr Syntax — No %% Prefix

`%%` is the Mermaid comment prefix. Lines written as %%accTitle … or %%accDescr … are comments and are silently ignored — this produces no accessibility metadata at all while looking like it works.

# WRONG — these are Mermaid comments and do nothing
%%accTitle This is ignored as a comment
%%accDescr This is also ignored as a comment

Correct syntax uses accTitle: and accDescr: directly, with no comment prefix:

flowchart TD
    accTitle: Account recovery decision flow
    A[Submit email address] --> B{Account found?}
    B -->|Yes| C[Send recovery link]
    B -->|No| D[Show recovery help]

Single-line description uses a colon:

flowchart LR
    accTitle: Publishing workflow
    accDescr: Content moves from drafting through accessibility review to publication.
    A[Draft] --> B[Accessibility review] --> C[Publish]

For a multi-line description, omit the colon after accDescr and use braces:

flowchart TD
    accTitle: Account recovery decision flow
    accDescr {
      A user submits an email address. If an account is found, the system sends
      a recovery link and confirms that it was sent. If no account is found,
      the system shows recovery help and offers a support contact.
    }
    A[Submit email address] --> B{Account found?}
    B -->|Yes| C[Send recovery link]
    B -->|No| D[Show recovery help]

Mermaid does not define a universal 100-character title limit or 500- character description limit — write the shortest title that distinguishes the diagram on the page, and keep the description concise enough to be useful as an image description (move detailed steps into visible structured HTML instead of stuffing them into accDescr).

Do not invent directives like %%a11y-node or %%a11y-edge — these are not standard Mermaid syntax; they're comments unless a project-specific preprocessor implements them, and should never be documented as Mermaid features.

Parse and render the source with the project's exact Mermaid version to catch syntax-support and diagram-type differences — accTitle/accDescr support varies by version and diagram type.

Writing Useful Titles and Descriptions

Title: identifies the subject, distinguishes it from others on the page, includes the diagram type only when it helps, avoids filenames/internal IDs/ generic labels ("Diagram"). Examples: "Account recovery decision flow", "Payment service request sequence", "Order states and permitted transitions".

Description: states the purpose, starting context, main elements/ participants, essential sequence/hierarchy/relationships, important decisions/exceptions/outcomes, and where a complete alternative is available. Do not merely list colors and shapes ("A blue rectangle points to a green diamond" describes appearance, not meaning) and do not flatten every node label into one long sentence — that's hard to navigate and loses structure.

Also provide a visible title/description — a page heading or figure caption helps everyone, not just AT users:

<figure aria-labelledby="recovery-flow-heading">
  <h2 id="recovery-flow-heading">Account recovery flow</h2>
  <pre class="mermaid">
flowchart TD
    accTitle: Account recovery decision flow
    accDescr: A recovery request either sends a link or offers additional help.
    A[Submit email address] --&gt; B{Account found?}
  </pre>
  <figcaption><a href="#recovery-flow-description">Read the account recovery steps</a>.</figcaption>
</figure>

(The > escaping is only needed when Mermaid source is embedded directly in HTML — Markdown Mermaid fences don't need it.)

Serious: Provide a Visible Structured Alternative for Complex Diagrams

accDescr creates an SVG description, not a navigable document structure. Complex diagrams need visible HTML with headings, lists, tables, and links.

<section id="recovery-flow-description" aria-labelledby="recovery-flow-description-heading">
  <h3 id="recovery-flow-description-heading">Account recovery steps</h3>
  <ol>
    <li>The user submits an email address.</li>
    <li>The system checks for an account:
      <ul>
        <li>If found, send a recovery link and confirm it was sent.</li>
        <li>If not found, show recovery help and offer support.</li>
      </ul>
    </li>
  </ol>
</section>

Keep alternatives synchronized — generate the diagram and its alternative from the same reviewed data model when possible; if maintained separately, require both in the same change, compare nodes/values/edges, and assign an owner for content review. Do not expose raw Mermaid source as the only alternative — it may help developers but is not an equivalent explanation for all users.

Serious: Understand Mermaid's Generated SVG (Do Not Hand-Author a Different Pattern)

Current Mermaid documentation states the renderer automatically adds aria-roledescription based on diagram type, and when accTitle/accDescr are provided, generates <title>/<desc> elements with aria-labelledby referencing the title and `aria-describedby` referencing the description — separately, not both combined into one aria-labelledby:

<svg aria-labelledby="generated-title-id"
     aria-describedby="generated-description-id"
     aria-roledescription="flowchart-v2"
     id="generated-diagram-id">
  <title id="generated-title-id">Account recovery decision flow</title>
  <desc id="generated-description-id">A recovery request either sends a link or offers additional help.</desc>
</svg>

Do not rewrite both as one `aria-labelledby` value without a tested reason — a label identifies the image; a description provides additional information; they're distinct relationships. Exact IDs/classes/attributes can change by Mermaid version — don't copy generated IDs into source or depend on undocumented internal class names.

Node-by-node semantics are not automatic. accTitle/accDescr describe the diagram as a whole — they do not make every node/edge/arrow a useful accessible object. Do not automatically add `role="list"`/`role="listitem"` to generated SVG groups — a visual layout is not necessarily a list, DOM order may not match reading order, and list semantics can't express branching, cardinality, or graph relationships. If users need to inspect individual items, build and test a purpose-specific interactive component — generated SVG internals are a fragile foundation for a complex widget.

IDs need to be unique in the final HTML document (not across unrelated pages). Let Mermaid manage its generated IDs; check for duplicates when several inline diagrams share a page; use deterministicIds config for stable snapshot testing; preserve every referenced ID through sanitization/export.

Serious: Embedding and Export Modes Change the Rules

<figure>
  <img src="account-recovery-flow.svg"
       alt="Account recovery either sends a reset link or provides additional support."
       width="960" height="540">
  <figcaption><a href="#recovery-flow-description">Read the complete account recovery steps</a>.</figcaption>
</figure>

Do not leave HTML alt empty just because the source SVG contains <title>/<desc>.

Choosing Clear Diagram Content

Nodes/participants: human-readable labels, not internal IDs; expand uncommon abbreviations; keep labels concise but meaningful; give visually similar nodes distinct textual labels; don't use shape alone to distinguish a decision/process/database/external system.

Edges/relationships: label branches when the outcome isn't otherwise clear — "Approved"/"Needs revision" over generic "Yes"/"No"; preserve direction and source→destination meaning in the alternative; explain unlabeled relationships depending on line style or position; don't use connector color alone to encode status or relationship type.

Reading order/layout: choose a direction matching content and document language; reduce line crossings; avoid layouts implying relationships through proximity alone. Visual placement is not a programmatic reading order — state the intended sequence/hierarchy in the description and structured alternative.

Moderate: Color and Contrast