mermaidlisted

# 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