11.9 KB437 lines
Blame
1> **Warning**
2>
3> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4>
5> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/accessibility.md](../../packages/mermaid/src/docs/config/accessibility.md).
6
7# Accessibility Options
8
9## Accessibility
10
11Now with Mermaid library in much wider use, we have started to work towards more accessible features, based on the feedback from the community.
12
13Adding accessibility means that the rich information communicated by visual diagrams can be made available to those using assistive technologies (and of course to search engines).
14[Read more about Accessible Rich Internet Applications and the W3 standards.](https://www.w3.org/WAI/standards-guidelines/aria/)
15
16Mermaid will automatically insert the [aria-roledescription](#aria-roledescription) and, if provided in the diagram text by the diagram author, the [accessible title and description.](#accessible-title-and-description)
17
18### aria-roledescription
19
20The [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) for the SVG HTML element is set to the diagram type key. (Note this may be slightly different than the keyword used for the diagram in the diagram text.)
21
22For example: The diagram type key for a state diagram is "stateDiagram". Here (a part of) the HTML of the SVG tag that shows the automatically inserted aria-roledescription set to "stateDiagram". _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
23
24```html
25<svg
26 aria-roledescription="stateDiagram"
27 class="statediagram"
28 xmlns="http://www.w3.org/2000/svg"
29 width="100%"
30 id="mermaid-1668720491568"
31></svg>
32```
33
34### Accessible Title and Description
35
36Support for accessible titles and descriptions is available for all diagrams/chart types. We have tried to keep the same keywords and format for all diagrams so that it is easy to understand and maintain.
37
38The accessible title and description will add `<title>` and `<desc>` elements within the SVG element and the [aria-labelledby](https://www.w3.org/TR/wai-aria/#aria-labelledby) and [aria-describedby](https://www.w3.org/TR/wai-aria/#aria-describedby) attributes in the SVG tag.
39
40Here is HTML that is generated, showing that the SVG element is labelled by the accessible title (id = `chart-title-mermaid-1668725057758`)
41and described by the accessible description (id = `chart-desc-mermaid-1668725057758` );
42and the accessible title element (text = "This is the accessible title")
43and the accessible description element (text = "This is an accessible description").
44
45_(Note that some of the SVG attributes and the SVG contents are omitted for clarity.)_
46
47```html
48<svg
49 aria-labelledby="chart-title-mermaid-1668725057758"
50 aria-describedby="chart-desc-mermaid-1668725057758"
51 xmlns="http://www.w3.org/2000/svg"
52 width="100%"
53 id="mermaid-1668725057758"
54>
55 <title id="chart-title-mermaid-1668725057758">This is the accessible title</title>
56 <desc id="chart-desc-mermaid-1668725057758">This is an accessible description</desc>
57</svg>
58```
59
60Details for the syntax follow.
61
62#### accessible title
63
64The **accessible title** is specified with the **accTitle** _keyword_, followed by a colon (`:`), and the string value for the title.
65The string value ends at the end of the line. (It can only be a single line.)
66
67Ex: `accTitle: This is a single line title`
68
69See [the accTitle and accDescr usage examples](#acctitle-and-accdescr-usage-examples) for how this can be used in a diagram and the resulting HTML generated.
70
71#### accessible description
72
73An accessible description can be 1 line long (a single line) or many lines long.
74
75The **single line accessible description** is specified with the **accDescr** _keyword_, followed by a colon (`:`), followed by the string value for the description.
76
77Ex: `accDescr: This is a single line description.`
78
79A **multiple line accessible description** _does not have a colon (`:`) after the accDescr keyword_ and is surrounded by curly brackets (`{}`).
80
81Ex:
82
83```markdown
84accDescr {
85This is a multiple line accessible description.
86It does not have a colon and is surrounded by curly brackets.
87}
88```
89
90See [the accTitle and accDescr usage examples](#acctitle-and-accdescr-usage-examples) for how this can be used in a diagram and the resulting HTML generated.
91
92#### accTitle and accDescr Usage Examples
93
94- Flowchart with the accessible title "Big Decisions" and the single-line accessible description "Bob's Burgers process for making big decisions"
95
96```mermaid-example
97 graph LR
98 accTitle: Big Decisions
99 accDescr: Bob's Burgers process for making big decisions
100 A[Identify Big Decision] --> B{Make Big Decision}
101 B --> D[Be done]
102```
103
104```mermaid
105 graph LR
106 accTitle: Big Decisions
107 accDescr: Bob's Burgers process for making big decisions
108 A[Identify Big Decision] --> B{Make Big Decision}
109 B --> D[Be done]
110```
111
112Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
113
114```html
115<svg
116 aria-labelledby="chart-title-mermaid_382ee221"
117 aria-describedby="chart-desc-mermaid_382ee221"
118 aria-roledescription="flowchart-v2"
119 xmlns="http://www.w3.org/2000/svg"
120 width="100%"
121 id="mermaid_382ee221"
122>
123 <title id="chart-title-mermaid_382ee221">Big decisions</title>
124 <desc id="chart-desc-mermaid_382ee221">Bob's Burgers process for making big decisions</desc>
125</svg>
126```
127
128- Flowchart with the accessible title "Bob's Burger's Making Big Decisions" and the multiple line accessible description "The official Bob's Burgers corporate processes that are used
129 for making very, very big decisions.
130 This is actually a very simple flow: identify the big decision and then make the big decision."
131
132```mermaid-example
133 graph LR
134 accTitle: Bob's Burger's Making Big Decisions
135 accDescr {
136 The official Bob's Burgers corporate processes that are used
137 for making very, very big decisions.
138 This is actually a very simple flow: identify the big decision and then make the big decision.
139 }
140 A[Identify Big Decision] --> B{Make Big Decision}
141 B --> D[Be done]
142```
143
144```mermaid
145 graph LR
146 accTitle: Bob's Burger's Making Big Decisions
147 accDescr {
148 The official Bob's Burgers corporate processes that are used
149 for making very, very big decisions.
150 This is actually a very simple flow: identify the big decision and then make the big decision.
151 }
152 A[Identify Big Decision] --> B{Make Big Decision}
153 B --> D[Be done]
154```
155
156Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
157
158```html
159<svg
160 aria-labelledby="chart-title-mermaid_382ee221"
161 aria-describedby="chart-desc-mermaid_382ee221"
162 aria-roledescription="flowchart-v2"
163 xmlns="http://www.w3.org/2000/svg"
164 width="100%"
165 id="mermaid_382ee221"
166>
167 <title id="chart-title-mermaid_382ee221">Big decisions</title>
168 <desc id="chart-desc-mermaid_382ee221">
169 The official Bob's Burgers corporate processes that are used for making very, very big
170 decisions. This is actually a very simple flow: identify the big decision and then make the big
171 decision.
172 </desc>
173</svg>
174```
175
176#### Sample Code Snippets for other diagram types
177
178##### Class Diagram
179
180```mermaid-example
181 classDiagram
182 accTitle: My Class Diagram
183 accDescr: My Class Diagram Description
184
185 Vehicle <|-- Car
186```
187
188```mermaid
189 classDiagram
190 accTitle: My Class Diagram
191 accDescr: My Class Diagram Description
192
193 Vehicle <|-- Car
194```
195
196##### Entity Relationship Diagram
197
198```mermaid-example
199 erDiagram
200 accTitle: My Entity Relationship Diagram
201 accDescr: My Entity Relationship Diagram Description
202
203 CUSTOMER ||--o{ ORDER : places
204 ORDER ||--|{ LINE-ITEM : contains
205 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
206
207```
208
209```mermaid
210 erDiagram
211 accTitle: My Entity Relationship Diagram
212 accDescr: My Entity Relationship Diagram Description
213
214 CUSTOMER ||--o{ ORDER : places
215 ORDER ||--|{ LINE-ITEM : contains
216 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
217
218```
219
220##### Gantt Chart
221
222```mermaid-example
223 gantt
224 accTitle: My Gantt Chart Accessibility Title
225 accDescr: My Gantt Chart Accessibility Description
226
227 title A Gantt Diagram
228 dateFormat YYYY-MM-DD
229 section Section
230 A task :a1, 2014-01-01, 30d
231 Another task :after a1 , 20d
232 section Another
233 Task in sec :2014-01-12 , 12d
234 another task : 24d
235
236```
237
238```mermaid
239 gantt
240 accTitle: My Gantt Chart Accessibility Title
241 accDescr: My Gantt Chart Accessibility Description
242
243 title A Gantt Diagram
244 dateFormat YYYY-MM-DD
245 section Section
246 A task :a1, 2014-01-01, 30d
247 Another task :after a1 , 20d
248 section Another
249 Task in sec :2014-01-12 , 12d
250 another task : 24d
251
252```
253
254##### GitGraph
255
256```mermaid-example
257 gitGraph
258 accTitle: My GitGraph Accessibility Title
259 accDescr: My GitGraph Accessibility Description
260
261 commit
262 commit
263 branch develop
264 checkout develop
265 commit
266 commit
267 checkout main
268 merge develop
269 commit
270 commit
271
272```
273
274```mermaid
275 gitGraph
276 accTitle: My GitGraph Accessibility Title
277 accDescr: My GitGraph Accessibility Description
278
279 commit
280 commit
281 branch develop
282 checkout develop
283 commit
284 commit
285 checkout main
286 merge develop
287 commit
288 commit
289
290```
291
292##### Pie Chart
293
294```mermaid-example
295 pie
296 accTitle: My Pie Chart Accessibility Title
297 accDescr: My Pie Chart Accessibility Description
298
299 title Key elements in Product X
300 "Calcium" : 42.96
301 "Potassium" : 50.05
302 "Magnesium" : 10.01
303 "Iron" : 5
304
305```
306
307```mermaid
308 pie
309 accTitle: My Pie Chart Accessibility Title
310 accDescr: My Pie Chart Accessibility Description
311
312 title Key elements in Product X
313 "Calcium" : 42.96
314 "Potassium" : 50.05
315 "Magnesium" : 10.01
316 "Iron" : 5
317
318```
319
320##### Requirement Diagram
321
322```mermaid-example
323 requirementDiagram
324 accTitle: My Requirement Diagram
325 accDescr: My Requirement Diagram Description
326
327 requirement test_req {
328 id: 1
329 text: the test text.
330 risk: high
331 verifymethod: test
332 }
333
334 element test_entity {
335 type: simulation
336 }
337
338 test_entity - satisfies -> test_req
339
340```
341
342```mermaid
343 requirementDiagram
344 accTitle: My Requirement Diagram
345 accDescr: My Requirement Diagram Description
346
347 requirement test_req {
348 id: 1
349 text: the test text.
350 risk: high
351 verifymethod: test
352 }
353
354 element test_entity {
355 type: simulation
356 }
357
358 test_entity - satisfies -> test_req
359
360```
361
362##### Sequence Diagram
363
364```mermaid-example
365 sequenceDiagram
366 accTitle: My Sequence Diagram
367 accDescr: My Sequence Diagram Description
368
369 Alice->>John: Hello John, how are you?
370 John-->>Alice: Great!
371 Alice-)John: See you later!
372```
373
374```mermaid
375 sequenceDiagram
376 accTitle: My Sequence Diagram
377 accDescr: My Sequence Diagram Description
378
379 Alice->>John: Hello John, how are you?
380 John-->>Alice: Great!
381 Alice-)John: See you later!
382```
383
384##### State Diagram
385
386```mermaid-example
387 stateDiagram
388 accTitle: My State Diagram
389 accDescr: My State Diagram Description
390
391 s1 --> s2
392
393```
394
395```mermaid
396 stateDiagram
397 accTitle: My State Diagram
398 accDescr: My State Diagram Description
399
400 s1 --> s2
401
402```
403
404##### User Journey Diagram
405
406```mermaid-example
407 journey
408 accTitle: My User Journey Diagram
409 accDescr: My User Journey Diagram Description
410
411 title My working day
412 section Go to work
413 Make tea: 5: Me
414 Go upstairs: 3: Me
415 Do work: 1: Me, Cat
416 section Go home
417 Go downstairs: 5: Me
418 Sit down: 5: Me
419
420```
421
422```mermaid
423 journey
424 accTitle: My User Journey Diagram
425 accDescr: My User Journey Diagram Description
426
427 title My working day
428 section Go to work
429 Make tea: 5: Me
430 Go upstairs: 3: Me
431 Do work: 1: Me, Cat
432 section Go home
433 Go downstairs: 5: Me
434 Sit down: 5: Me
435
436```
437