mermaid

Name: mermaid
Author: mgifford

27stars2forks

How to install mermaid?

mgifford/accessibility-skills/mermaid

$npx -y skills add mgifford/accessibility-skills --skill mermaid

Installs into the current project.

Summary

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. A

Files · 1

View on GitHub

SKILL.md

1	# Mermaid Diagrams Accessibility Skill
2
3	> Canonical source: `examples/MERMAID_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when authoring, generating, or reviewing Mermaid diagrams.
7	Only load this skill if the project uses Mermaid diagrams.
8
9	---
10
11	## Core Mandate
12
13	Accessible Mermaid content depends on four layers: (1) the diagram source and
14	its accessibility metadata, (2) the exact Mermaid renderer and configuration,
15	(3) the generated SVG/raster output, and (4) how the publishing platform
16	embeds and exposes that output. A generated Mermaid diagram is non-text
17	content unless the rendered nodes/relationships are proven to have useful
18	semantics — test the final published output, not just the source or an
19	editor preview.
20
21	Before authoring, decide whether a diagram is even needed — a heading, short
22	list, table, or few sentences may communicate the information more clearly.
23	Mermaid is useful when relationships, sequence, branching, hierarchy, timing,
24	or spatial grouping materially improve understanding.
25
26	---
27
28	## Severity Scale (this skill)
29
30	\| Level \| Meaning \|
31	\|---\|---\|
32	\| Critical \| Diagram conveys essential information with no accessible title or alternative; metadata written with the wrong syntax so it's silently ignored \|
33	\| Serious \| Title present but no description on a complex diagram; contrast fails \|
34	\| Moderate \| No visible structured alternative for a complex diagram type; named edges lack context \|
35	\| Minor \| Duplicate IDs; missing renderer-version verification \|
36
37	---
38
39	## Critical: Use the Correct `accTitle`/`accDescr` Syntax — No `%%` Prefix
40
41	`%%` is the Mermaid comment prefix. Lines written as `%%accTitle …` or
42	`%%accDescr …` are comments and are silently ignored — this produces no
43	accessibility metadata at all while looking like it works.
44
45	```
46	# WRONG — these are Mermaid comments and do nothing
47	%%accTitle This is ignored as a comment
48	%%accDescr This is also ignored as a comment
49	```
50
51	Correct syntax uses `accTitle:` and `accDescr:` directly, with no comment prefix:
52
53	```mermaid
54	flowchart TD
55	accTitle: Account recovery decision flow
56	A[Submit email address] --> B{Account found?}
57	B -->\|Yes\| C[Send recovery link]
58	B -->\|No\| D[Show recovery help]
59	```
60
61	Single-line description uses a colon:
62
63	```mermaid
64	flowchart LR
65	accTitle: Publishing workflow
66	accDescr: Content moves from drafting through accessibility review to publication.
67	A[Draft] --> B[Accessibility review] --> C[Publish]
68	```
69
70	For a multi-line description, omit the colon after `accDescr` and use braces:
71
72	```mermaid
73	flowchart TD
74	accTitle: Account recovery decision flow
75	accDescr {
76	A user submits an email address. If an account is found, the system sends
77	a recovery link and confirms that it was sent. If no account is found,
78	the system shows recovery help and offers a support contact.
79	}
80	A[Submit email address] --> B{Account found?}
81	B -->\|Yes\| C[Send recovery link]
82	B -->\|No\| D[Show recovery help]
83	```
84
85	Mermaid does not define a universal 100-character title limit or 500-
86	character description limit — write the shortest title that distinguishes
87	the diagram on the page, and keep the description concise enough to be
88	useful as an image description (move detailed steps into visible structured
89	HTML instead of stuffing them into `accDescr`).
90
91	Do not invent directives like `%%a11y-node` or `%%a11y-edge` — these are
92	not standard Mermaid syntax; they're comments unless a project-specific
93	preprocessor implements them, and should never be documented as Mermaid features.
94
95	Parse and render the source with the project's exact Mermaid version to
96	catch syntax-support and diagram-type differences — `accTitle`/`accDescr`
97	support varies by version and diagram type.
98
99	---
100
101	## Writing Useful Titles and Descriptions
102
103	Title: identifies the subject, distinguishes it from others on the page,
104	includes the diagram type only when it helps, avoids filenames/internal IDs/
105	generic labels ("Diagram"). Examples: "Account recovery decision flow",
106	"Payment service request sequence", "Order states and permitted transitions".
107
108	Description: states the purpose, starting context, main elements/
109	participants, essential sequence/hierarchy/relationships, important
110	decisions/exceptions/outcomes, and where a complete alternative is available.
111	Do not merely list colors and shapes ("A blue rectangle points to a g

People who liked this also viewed

6 picks

Type

mermaid

27stars2forks

View on GitHub

How to install mermaid?

mgifford/accessibility-skills/mermaid

$npx -y skills add mgifford/accessibility-skills --skill mermaid

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Mermaid Diagrams Accessibility Skill
2
3	> Canonical source: `examples/MERMAID_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when authoring, generating, or reviewing Mermaid diagrams.
7	Only load this skill if the project uses Mermaid diagrams.
8
9	---
10
11	## Core Mandate
12
13	Accessible Mermaid content depends on four layers: (1) the diagram source and
14	its accessibility metadata, (2) the exact Mermaid renderer and configuration,
15	(3) the generated SVG/raster output, and (4) how the publishing platform
16	embeds and exposes that output. A generated Mermaid diagram is non-text
17	content unless the rendered nodes/relationships are proven to have useful
18	semantics — test the final published output, not just the source or an
19	editor preview.
20
21	Before authoring, decide whether a diagram is even needed — a heading, short
22	list, table, or few sentences may communicate the information more clearly.
23	Mermaid is useful when relationships, sequence, branching, hierarchy, timing,
24	or spatial grouping materially improve understanding.
25
26	---
27
28	## Severity Scale (this skill)
29
30	\| Level \| Meaning \|
31	\|---\|---\|
32	\| Critical \| Diagram conveys essential information with no accessible title or alternative; metadata written with the wrong syntax so it's silently ignored \|
33	\| Serious \| Title present but no description on a complex diagram; contrast fails \|
34	\| Moderate \| No visible structured alternative for a complex diagram type; named edges lack context \|
35	\| Minor \| Duplicate IDs; missing renderer-version verification \|
36
37	---
38
39	## Critical: Use the Correct `accTitle`/`accDescr` Syntax — No `%%` Prefix
40
41	`%%` is the Mermaid comment prefix. Lines written as `%%accTitle …` or
42	`%%accDescr …` are comments and are silently ignored — this produces no
43	accessibility metadata at all while looking like it works.
44
45	```
46	# WRONG — these are Mermaid comments and do nothing
47	%%accTitle This is ignored as a comment
48	%%accDescr This is also ignored as a comment
49	```
50
51	Correct syntax uses `accTitle:` and `accDescr:` directly, with no comment prefix:
52
53	```mermaid
54	flowchart TD
55	accTitle: Account recovery decision flow
56	A[Submit email address] --> B{Account found?}
57	B -->\|Yes\| C[Send recovery link]
58	B -->\|No\| D[Show recovery help]
59	```
60
61	Single-line description uses a colon:
62
63	```mermaid
64	flowchart LR
65	accTitle: Publishing workflow
66	accDescr: Content moves from drafting through accessibility review to publication.
67	A[Draft] --> B[Accessibility review] --> C[Publish]
68	```
69
70	For a multi-line description, omit the colon after `accDescr` and use braces:
71
72	```mermaid
73	flowchart TD
74	accTitle: Account recovery decision flow
75	accDescr {
76	A user submits an email address. If an account is found, the system sends
77	a recovery link and confirms that it was sent. If no account is found,
78	the system shows recovery help and offers a support contact.
79	}
80	A[Submit email address] --> B{Account found?}
81	B -->\|Yes\| C[Send recovery link]
82	B -->\|No\| D[Show recovery help]
83	```
84
85	Mermaid does not define a universal 100-character title limit or 500-
86	character description limit — write the shortest title that distinguishes
87	the diagram on the page, and keep the description concise enough to be
88	useful as an image description (move detailed steps into visible structured
89	HTML instead of stuffing them into `accDescr`).
90
91	Do not invent directives like `%%a11y-node` or `%%a11y-edge` — these are
92	not standard Mermaid syntax; they're comments unless a project-specific
93	preprocessor implements them, and should never be documented as Mermaid features.
94
95	Parse and render the source with the project's exact Mermaid version to
96	catch syntax-support and diagram-type differences — `accTitle`/`accDescr`
97	support varies by version and diagram type.
98
99	---
100
101	## Writing Useful Titles and Descriptions
102
103	Title: identifies the subject, distinguishes it from others on the page,
104	includes the diagram type only when it helps, avoids filenames/internal IDs/
105	generic labels ("Diagram"). Examples: "Account recovery decision flow",
106	"Payment service request sequence", "Order states and permitted transitions".
107
108	Description: states the purpose, starting context, main elements/
109	participants, essential sequence/hierarchy/relationships, important
110	decisions/exceptions/outcomes, and where a complete alternative is available.
111	Do not merely list colors and shapes ("A blue rectangle points to a g

People who liked this also viewed

6 picks

Type