How Mermaid's Accessibility System Generates ARIA Attributes for Screen Reader Compatibility

Mermaid automatically injects ARIA attributes like role="img", aria-label, and aria-describedby into every SVG diagram, creating hidden <title> and <desc> elements that allow screen readers to convey visual flowcharts as semantic text.

The mermaid-js/mermaid repository embeds accessibility support directly into its rendering pipeline. When you define a diagram using Mermaid's text-based syntax, the accessibility system analyzes the structure and automatically generates ARIA attributes that make the resulting SVG comprehensible to assistive technologies. This ensures that screen reader users receive meaningful descriptions of node relationships, flow directions, and diagram purpose without requiring manual HTML markup.

How the Mermaid Accessibility System Operates

The accessibility system follows a multi-stage pipeline that transforms textual diagram definitions into semantically rich SVG output. According to the mermaid-js/mermaid source code, this process involves three core phases: parsing the diagram into an abstract syntax tree (AST), generating textual descriptions, and injecting ARIA attributes into the final SVG.

Diagram Parsing and AST Generation

The process begins in the diagram-specific parser logic, such as packages/mermaid/src/diagrams/flowchart/parser.ts. Here, the textual definition is converted into an AST that represents nodes, edges, and structural relationships. This AST serves as the foundation for accessibility enrichment, providing the accessibility module with a complete map of the diagram's elements and connections.

Building Textual Descriptions

Before SVG emission, the accessibility.ts module (located at packages/mermaid/src/diagrams/flowchart/accessibility.ts) traverses the AST to construct human-readable descriptions. For a flowchart with four nodes and three edges, the module might generate a summary like "Flowchart with 4 nodes and 3 edges" and a detailed description mapping the flow between specific elements. These strings feed directly into the ARIA attributes that screen readers will announce.

SVG Injection and ARIA Attributes

The final rendering stage occurs in packages/mermaid/src/svgRenderer.ts, which attaches the generated descriptions to the SVG root element and key sub-elements. The system automatically applies four critical accessibility properties:

• role="img" – Signals to screen readers that the SVG should be treated as a single image entity rather than a collection of unrelated graphics.
• aria-label – Contains a concise summary of the diagram, derived from the title: directive or auto-generated from node/edge counts.
• aria-labelledby – References a hidden <title> element within the SVG, ensuring compatibility with browsers that prioritize the <title> tag over the attribute.
• aria-describedby – Points to a <desc> element containing the longer, detailed description of nodes, edges, and flow direction.

These attributes work in concert with hidden <title> and <desc> tags inserted directly into the SVG markup, which remain invisible to sighted users but fully exposed to assistive technology.

Customizing ARIA Attributes and Descriptions

While Mermaid generates baseline accessibility text automatically, diagram authors can override these values to provide context-specific descriptions. The system reads custom accessibility settings from directive blocks and applies them during the enrichment phase.

Overriding the Title with Directives

The title: directive in the diagram definition overrides the auto-generated aria-label. For example:

flowchart TD
    title My Purchase Approval Flow
    A[Request] --> B{Manager Approval}
    B -->|Approved| C[Procurement]

In this case, the SVG root receives aria-label="My Purchase Approval Flow" instead of a generic node count summary.

Providing Detailed Descriptions via Init Blocks

For longer descriptions, authors use the %%{init}%% configuration block processed by packages/mermaid/src/diagramAPI.ts. This allows specification of custom text for the aria-describedby reference:

%%{init: {'accessibility': { 'description': 'A flowchart showing purchase approval process with manager review gates.' }}}%%
flowchart LR
    A[Request] --> B{Manager Approval}
    B -->|Approved| C[Procurement]
    B -->|Rejected| D[Notify Requester]

The resulting SVG contains a <desc> element with the custom text, referenced by aria-describedby, while the aria-label remains auto-generated unless explicitly overridden.

Summary

• Mermaid's accessibility system automatically injects ARIA attributes into every SVG diagram during the rendering pipeline.
• The process involves parsing diagrams into ASTs via parser.ts, generating descriptions in accessibility.ts, and rendering final output in svgRenderer.ts.
• Automatically applied attributes include role="img", aria-label, aria-labelledby, and aria-describedby, paired with hidden <title> and <desc> elements.
• Diagram authors can customize accessibility text using the title: directive for labels or %%{init: {'accessibility': {...}}}%% blocks for detailed descriptions.
• Even without explicit configuration, Mermaid produces meaningful structural summaries based on node counts and edge directions to ensure baseline screen reader compatibility.

Frequently Asked Questions

What ARIA attributes does Mermaid automatically generate for diagrams?

Mermaid automatically applies role="img" to the SVG root, along with aria-label for concise summaries and aria-describedby pointing to detailed descriptions. It also adds aria-labelledby referencing a hidden <title> element to maximize browser compatibility with screen readers.

How can I provide custom accessibility text for a Mermaid diagram?

You can override the automatic label by adding a title: directive to your diagram definition. For detailed descriptions, use the %%{init: {'accessibility': { 'description': 'Your text here' }}}%% configuration block, which diagramAPI.ts parses to populate the aria-describedby reference.

Does Mermaid generate accessibility descriptions if I don't provide any?

Yes. If you provide no accessibility hints, the accessibility.ts module analyzes the AST from parser.ts to generate descriptions based on diagram structure, such as "Flowchart with 4 nodes and 3 edges" and textual mappings of node connections. This ensures every diagram has baseline screen reader support.

Which source files control Mermaid's accessibility system?

The core logic resides in packages/mermaid/src/diagrams/flowchart/accessibility.ts for description generation, packages/mermaid/src/svgRenderer.ts for SVG element injection, and packages/mermaid/src/diagramAPI.ts for parsing accessibility overrides from init blocks. Diagram-specific parsers like packages/mermaid/src/diagrams/flowchart/parser.ts supply the AST data required for structural analysis.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}