# Mermaid
> Load this skill whenever the project uses Mermaid diagrams — flowcharts, sequence diagrams, class diagrams, Gantt charts, or any Mermaid-rendered visualization. Under no circumstances render a Mermaid diagram without an accessible title, description, and text-based alternative. Absolutely always add accTitle: and accDescr: (no %% prefix — that is the comment syntax and will be silently ignored) to every diagram.
- Skill: `mgifford/mermaid` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mgifford/mermaid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mgifford/mermaid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mgifford (https://skillmd.com/u/mgifford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mgifford/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)
| Level | Meaning |
|---|---|
| **Critical** | Diagram conveys essential information with no accessible title or alternative; metadata written with the wrong syntax so it's silently ignored |
| **Serious** | Title present but no description on a complex diagram; contrast fails |
| **Moderate** | No visible structured alternative for a complex diagram type; named edges lack context |
| **Minor** | Duplicate IDs; missing renderer-version verification |
---
## 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:
```mermaid
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:
```mermaid
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:
```mermaid
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:
```html
Account recovery flow
flowchart TD
accTitle: Account recovery decision flow
accDescr: A recovery request either sends a link or offers additional help.
A[Submit email address] --> B{Account found?}
Read the account recovery steps.
```
(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.
| Mermaid diagram type | Useful structured alternative |
|---|---|
| Flowchart / decision tree | Ordered steps + nested lists or a decision table (conditions → outcomes) |
| Sequence diagram | Participant list + chronological message table |
| State diagram | State definitions + transition table (trigger, source, destination, outcome) |
| Class diagram | Class definitions, properties, methods, inheritance, relationship table |
| Entity relationship | Entity definitions, keys, attributes, cardinality, relationship table |
| Gantt / timeline | Task/event table with dates, duration, owner, status, dependencies |
| Pie/XY/quadrant/radar/Sankey | Summary of findings + underlying data table with units |
| Mind map / tree | Properly nested heading or list hierarchy |
| Architecture/C4/block | Component inventory, responsibilities, boundaries, relationship table |
| Git graph | Chronological branch/merge/release history |
| User journey | Ordered stages, goals, actions, emotions, barriers, opportunities |
```html
Account recovery steps
The user submits an email address.
The system checks for an account:
If found, send a recovery link and confirm it was sent.
If not found, show recovery help and offer support.
```
**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 ``/`<desc>` elements with `aria-labelledby`
referencing the title and **`aria-describedby`** referencing the description
— **separately**, not both combined into one `aria-labelledby`:
```html
<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 flowA recovery request either sends a link or offers additional help.
```
**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
| Mode | Responsibility |
|---|---|
| Inline SVG generated in the page | Preserve generated title/description/ARIA references, language, styles, unique IDs |
| External SVG via `` | Give the HTML `alt` — do not assume the SVG's internal title/desc are exposed |
| Raster PNG/JPEG | HTML `alt` + long structured alternative in HTML |
| `