Making Mermaid diagrams accessible for screen readers and assistive technology

Diagrams are powerful teaching tools—but only if everyone can access them. Screen reader users, people with cognitive disabilities, and those on slower connections all deserve to understand your flowcharts, architecture diagrams, and workflows. Mermaid diagrams, when built with accessibility in mind, can be interpreted by assistive technology and exported with semantic meaning.

Why diagram accessibility matters

Visual diagrams encode information that isn't always available in surrounding text. Without accessible alternatives:

• Screen reader users hear only the image filename or a generic "diagram" label
• Cognitive load increases — people with reading or processing disabilities may struggle to parse dense visual structures
• Mobile users on slow connections see broken images
• Search engines miss the content (bad for SEO)
• Compliance risk — WCAG 2.1 Level AA requires text alternatives for images

Accessible diagrams are a legal and ethical requirement, not a nice-to-have.

The accessibility layer: beyond alt text

Mermaid diagrams don't have built-in screen reader support (yet), but you can make them accessible through:

1. Semantic HTML labels — descriptive titles and descriptions
2. Detailed alt text — summarizing the diagram's meaning
3. Text descriptions — explaining the diagram in prose
4. Data tables — for data-heavy diagrams (Sankey, pie charts)
5. Logical structure — clear labels, consistent shapes, minimal jargon

Strategy 1: Descriptive alt text

Alt text should describe the meaning of the diagram, not just what it shows. Poor vs. good:

Poor:
"A diagram showing a flowchart."

Good:
"A flowchart showing the user registration process: email entry leads to account creation, which branches to either email verification (success) or retry (failure). On success, the user reaches the dashboard."

Alt text guidelines:

• Aim for 100–150 characters (under 255 if possible)
• Use plain language (avoid "Figure 3a")
• Include the key decision points or outcome
• For complex diagrams, prefix with "Complex diagram:" to signal that a longer description follows

Example in Markdown with alt text:

![A flowchart showing user registration: email → account creation → email verification or retry → dashboard.](diagram.svg)

Strategy 2: Detailed text descriptions

For complex diagrams, alt text alone isn't enough. Provide a detailed description below or nearby:

## User Registration Flow

![Flowchart: user registration process.](flowchart.svg)

**Diagram description:**  
1. User enters email address
2. System creates account
3. Email is sent to verify ownership
4. If verified: user reaches dashboard and can log in
5. If not verified within 24h: account is deleted; user must restart registration

This approach:

• Gives screen reader users the full picture
• Helps people with cognitive disabilities process step-by-step
• Provides context for low-vision users who may see the image fuzzily
• Improves SEO (search engines read text descriptions)

Strategy 3: Accessible Mermaid code structure

Even though Mermaid doesn't embed screen reader descriptions yet, clean code makes diagrams easier to understand when exported or converted. Use:

1. Semantic labels — avoid cryptic abbreviations

   flowchart LR
       A["User Email"] --> B["Validate Email Format"]
       B --> C{Email Valid?}
       C -->|Yes| D["Create Account"]
       C -->|No| E["Show Error Message"]
   

2. Full node text — descriptive not abbreviated

   flowchart LR
       Start["User clicks 'Sign Up'"]
       Input["Enter email and password"]
       Start --> Input
   

3. Logical order — structure your code so reading top-to-bottom tells a story

   flowchart TD
       Start["Begin"]
       Step1["Step 1: Collect data"]
       Step2["Step 2: Validate data"]
       Step3["Step 3: Save to database"]
       End["Success"]
       
       Start --> Step1
       Step1 --> Step2
       Step2 --> Step3
       Step3 --> End
   

Strategy 4: Data tables for visual data

For pie charts, bar charts, or Sankey diagrams showing data, provide the data in a table:

Visual (Mermaid pie chart):

pie title User Distribution by Region
    "North America" : 45
    "Europe" : 30
    "Asia" : 20
    "Other" : 5

Accessible table:

Region	Users	Percentage
North America	45	45%
Europe	30	30%
Asia	20	20%
Other	5	5%

Screen reader users can navigate and understand the data, and they can sort/compare columns. The table is also easier to update and version-control than images.

Real-world example: accessible architecture diagram

Here's an architecture diagram with layered accessibility:

1. Mermaid code (semantic structure):

graph TD
    subgraph Clients["Client Layer"]
        Web["Web Browser<br/>React App"]
        Mobile["Mobile App<br/>iOS + Android"]
    end
    
    subgraph API["API Layer"]
        Gateway["API Gateway<br/>Authentication"]
        Service["User Service<br/>Microservice"]
    end
    
    subgraph Data["Data Layer"]
        DB["PostgreSQL<br/>User Database"]
        Cache["Redis<br/>Session Cache"]
    end
    
    Web --> Gateway
    Mobile --> Gateway
    Gateway --> Service
    Service --> DB
    Service --> Cache

2. HTML with alt text:

<figure>
  <img 
    src="architecture.svg" 
    alt="Architecture diagram showing three layers: Clients (web and mobile), API (gateway and service), Data (database and cache). Clients route to gateway; gateway routes to service; service connects to both database and cache."
  >
  <figcaption>System Architecture Overview</figcaption>
</figure>

3. Detailed text description below the figure:

## Architecture Overview

The system consists of three layers:

**Client Layer**: Web and mobile applications where users interact with the system.

**API Layer**: 
- API Gateway handles authentication and routes requests
- User Service processes business logic (CRUD operations, validation)

**Data Layer**:
- PostgreSQL stores persistent user data
- Redis caches sessions and frequently accessed user preferences

Data flow: Client → API Gateway → User Service → Database or Cache

4. Optional: Data table for non-visual understanding

| Component | Type | Purpose |
| --- | --- | --- |
| Web Browser | Client | Desktop user interface |
| Mobile App | Client | Mobile user interface |
| API Gateway | Middleware | Authentication & routing |
| User Service | Microservice | Business logic |
| PostgreSQL | Database | Persistent storage |
| Redis | Cache | Session & preference caching |

This multi-layered approach ensures:

• Screen reader users hear a clear alt text + detailed description
• Low-vision users see the image + context
• Search engines understand the architecture
• Everyone, including mobile users, has access to the data

Mermaid-specific accessibility tips

1. Avoid color alone for meaning — use labels and shapes too

   graph LR
       A["User Input"] --> B{Valid?}
       B -->|Yes| C["Process"]
       B -->|No| D["Error"]
   

   The shapes (square, diamond) convey meaning; colors enhance it.

2. Use subgraphs to group related items — helps screen reader users understand structure

   graph TD
       subgraph Frontend["Frontend Services"]
           A["UI"]
           B["Router"]
       end
       
       subgraph Backend["Backend Services"]
           C["API"]
           D["Database"]
       end
   

3. Label edges for complex relationships — don't rely on arrow position

   graph LR
       A["Service A"] -->|"calls synchronously"| B["Service B"]
       A -->|"publishes to"| C["Message Queue"]
   

4. Keep text concise — large node labels become hard to read with zoom/magnification

   flowchart LR
       A["Login"] --> B["Authenticate"]
       B --> C["Dashboard"]
   

5. Test with a screen reader — use free tools like NVDA (Windows) or VoiceOver (Mac) to verify your descriptions

Exporting diagrams for accessibility

When exporting Mermaid diagrams:

• SVG format — supports semantic structure better than PNG; include title/description tags
• Add metadata — in SVG export, include <title> and <desc> elements

  <svg>
    <title>User Registration Flowchart</title>
    <desc>A flowchart showing: email entry → account creation → email verification → dashboard</desc>
    <!-- diagram content -->
  </svg>
  

• Keep Markdown source — version the source .md files alongside diagrams so others can regenerate or modify

WCAG compliance checklist

WCAG Criterion	How to meet it with Mermaid
1.1.1 Non-text Content (A)	Provide alt text describing the diagram's meaning
1.4.3 Contrast (AA)	Ensure text in diagram meets 4.5:1 ratio; avoid color-only encoding
1.4.11 Non-text Contrast (AA)	Diagram elements should have 3:1 contrast ratio
2.4.4 Link Purpose (A)	If diagram links to other pages, label them clearly
4.1.2 Name, Role, Value (A)	Use semantic labels (flowchart shapes have clear roles)

FAQ

Do I need alt text if I have a detailed description below the diagram?
Yes. Alt text appears when images fail to load and is read immediately by screen readers. A description provides additional context. Use both.

Can I make Mermaid diagrams interactive and accessible?
Partially. If you embed Mermaid in a web page, you can add ARIA labels and descriptions to the SVG output. Focus on clear semantics and text descriptions for now.

What's the best format for diagrams: PNG, SVG, or embedded Mermaid?

• SVG — best for accessibility (scalable, supports metadata, embeddable)
• Embedded Mermaid — improves performance and SEO but requires semantic labeling
• PNG — worst for accessibility; only use when SVG/Mermaid can't render

How do I document diagrams for people who are blind?
Detailed prose descriptions (100+ words) work best. Read your description aloud—does it paint a clear picture without the visual? If yes, you're there.

Are there tools to auto-generate alt text for diagrams?
Not yet. AI models can describe images but may miss the specific domain knowledge your diagram encodes. Write descriptions yourself; they're worth the effort.

Create inclusive diagrams in the MermaidCreator editor. Accessible design means your work reaches and helps everyone on your team and in your audience.