mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-01-14 06:43:25 +08:00
doc: revise A11y: fix multi-line ex, +describedby, alpha sort examples
This commit is contained in:
parent
0adc6a6112
commit
4fb4aa417c
@ -14,8 +14,8 @@ This would be to define a jison grammar for the new diagram type. That should st
|
||||
|
||||
For instance:
|
||||
|
||||
- the flowchart starts with the keyword graph.
|
||||
- the sequence diagram starts with the keyword sequenceDiagram
|
||||
- the flowchart starts with the keyword _graph_
|
||||
- the sequence diagram starts with the keyword _sequenceDiagram_
|
||||
|
||||
#### Store data found during parsing
|
||||
|
||||
@ -61,6 +61,11 @@ Place the renderer in the diagram folder.
|
||||
### Step 3: Detection of the new diagram type
|
||||
|
||||
The second thing to do is to add the capability to detect the new new diagram to type to the detectType in utils.js. The detection should return a key for the new diagram type.
|
||||
[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type.
|
||||
For example, if your new diagram use a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader
|
||||
would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram.
|
||||
|
||||
Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same.
|
||||
|
||||
### Step 4: The final piece - triggering the rendering
|
||||
|
||||
@ -168,17 +173,23 @@ It is probably a good idea to keep the handling similar to this in your new diag
|
||||
|
||||
## Accessibility
|
||||
|
||||
The syntax for adding title and description looks like this:
|
||||
Mermaid automatically adds the following accessibility information for the diagram SVG HTML element:
|
||||
|
||||
accTitle: The title
|
||||
accDescr: The description
|
||||
- aria-roledescription
|
||||
- accessible title
|
||||
- accessible description
|
||||
|
||||
accDescr {
|
||||
Syntax for a description text
|
||||
written on multiple lines.
|
||||
}
|
||||
### aria-roledescription
|
||||
|
||||
In a similar way to the directives the jison syntax are quite similar between the diagrams.
|
||||
The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element.
|
||||
|
||||
See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) in [the Accessible Rich Internet Applications W3 standard.](https://www.w3.org/WAI/standards-guidelines/aria/)
|
||||
|
||||
### accessible title and description
|
||||
|
||||
The syntax for accessible titles and descriptions is described in [the Accessibility documenation section.](../config/accessibility.md)
|
||||
|
||||
In a similar way to the directives, the jison syntax are quite similar between the diagrams.
|
||||
|
||||
```jison
|
||||
|
||||
@ -214,20 +225,7 @@ The functions for setting title and description are provided by a common module.
|
||||
clear as commonClear,
|
||||
} from '../../commonDb';
|
||||
|
||||
Starting with Mermaid version, the accessibility tags are inserted into the SVG element in the `render` function in mermaidAPI.
|
||||
|
||||
In version \_\_\_ and before, you need to insert the accessibility tags in your renderer:
|
||||
|
||||
**In the renderer:**
|
||||
|
||||
```js
|
||||
import addSVGAccessibilityFields from '../../accessibility';
|
||||
|
||||
/* ... */
|
||||
|
||||
// Adds title and description to the flow chart
|
||||
addSVGAccessibilityFields(parser.yy, svg, id);
|
||||
```
|
||||
The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI.
|
||||
|
||||
## Theming
|
||||
|
||||
|
@ -10,118 +10,169 @@
|
||||
|
||||
Now with Mermaid library in much wider use, we have started to work towards more accessible features, based on the feedback from the community.
|
||||
|
||||
To begin with, we have added a new feature to Mermaid library, which is to support accessibility options, **Accessibility Title** and **Accessibility Description**.
|
||||
Adding 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).
|
||||
[Read more about Accessible Rich Internet Applications and the W3 standards.](https://www.w3.org/WAI/standards-guidelines/aria/)
|
||||
|
||||
This support for accessibility options is available for all the diagrams/chart types. Also, we have tired to keep the same format for the accessibility options, so that it is easy to understand and maintain.
|
||||
Mermaid 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)
|
||||
|
||||
## Defining Accessibility Options
|
||||
### aria-roledescription
|
||||
|
||||
### Single line accessibility values
|
||||
The [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.)
|
||||
|
||||
The diagram authors can now add the accessibility options in the diagram definition, using the `accTitle` and `accDescr` keywords, where each keyword is followed by `:` and the string value for title and description like:
|
||||
For 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-roledscription set to "stateDiagram". _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
|
||||
|
||||
- `accTitle: "Your Accessibility Title"` or
|
||||
- `accDescr: "Your Accessibility Description"`
|
||||
```html
|
||||
<svg
|
||||
aria-roledescription="stateDiagram"
|
||||
class="statediagram"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
width="100%"
|
||||
id="mermaid-1668720491568"
|
||||
></svg>
|
||||
```
|
||||
|
||||
**When these two options are defined, they will add a corresponding `<title>` and `<desc>` tag in the SVG.**
|
||||
### Accessible Title and Description
|
||||
|
||||
Let us take a look at the following example with a flowchart diagram:
|
||||
Support 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.
|
||||
|
||||
The 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.
|
||||
|
||||
Here is HTML that is generated, showing that the SVG element is labelled by the accessible title (id = `chart-title-mermaid-1668725057758`)
|
||||
and described by the accessible description (id = `chart-desc-mermaid-1668725057758` );
|
||||
and the accessible title element (text = "This is the accessible title")
|
||||
and the accessible description element (text = "This is an accessible description").
|
||||
|
||||
_(Note that some of the SVG attributes and the SVG contents are omitted for clarity.)_
|
||||
|
||||
```html
|
||||
<svg
|
||||
aria-labelledby="chart-title-mermaid-1668725057758"
|
||||
aria-describedby="chart-desc-mermaid-1668725057758"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
width="100%"
|
||||
id="mermaid-1668725057758"
|
||||
>
|
||||
<title id="chart-title-mermaid-1668725057758">This is the accessible title</title>
|
||||
<desc id="chart-desc-mermaid-1668725057758">This is an accessible description</desc>
|
||||
</svg>
|
||||
```
|
||||
|
||||
Details for the syntax follow.
|
||||
|
||||
#### accessible title
|
||||
|
||||
The **accessible title** is specified with the **accTitle** _keyword_, followed by a colon (`:`), and the string value for the title.
|
||||
The string value ends at the end of the line. (It can only be a single line.)
|
||||
|
||||
Ex: `accTitle: This is a single line title`
|
||||
|
||||
See [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.
|
||||
|
||||
#### accessible description
|
||||
|
||||
An accessible description can be 1 line long (a single line) or many lines long.
|
||||
|
||||
The **single line accessible description** is specified with the **accDescr** _keyword_, followed by a colon (`:`), followed by the string value for the description.
|
||||
|
||||
Ex: `accDescr: This is a single line description.`
|
||||
|
||||
A **multiple line accessible description** _does not have a colon (`:`) after the accDescr keyword_ and is surrounded by curly brackets (`{}`).
|
||||
|
||||
Ex:
|
||||
|
||||
accDescr { The official Bob's Burgers corporate processes that are used
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: see the big decision and then make the big decision.}
|
||||
|
||||
See [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.
|
||||
|
||||
#### accTitle and accDescr Usage Examples
|
||||
|
||||
- Flowchart with the accessible title "Big Decisions" and the single-line accessible description "Bob's Burgers process for making big decisions"
|
||||
|
||||
```mermaid-example
|
||||
graph LR
|
||||
accTitle: Big decisions
|
||||
accDescr: Flow chart of the decision making process
|
||||
A[Hard] -->|Text| B(Round)
|
||||
B --> C{Decision}
|
||||
C -->|One| D[Result 1]
|
||||
|
||||
graph LR
|
||||
accTitle: Big Decisions
|
||||
accDescr: Bob's Burgers process for making big decisions
|
||||
A[Identify Big Descision] --> B{Make Big Decision}
|
||||
B --> D[Be done]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
accTitle: Big decisions
|
||||
accDescr: Flow chart of the decision making process
|
||||
A[Hard] -->|Text| B(Round)
|
||||
B --> C{Decision}
|
||||
C -->|One| D[Result 1]
|
||||
|
||||
graph LR
|
||||
accTitle: Big Decisions
|
||||
accDescr: Bob's Burgers process for making big decisions
|
||||
A[Identify Big Descision] --> B{Make Big Decision}
|
||||
B --> D[Be done]
|
||||
```
|
||||
|
||||
See in the code snippet above, the `accTitle` and `accDescr` are defined in the diagram definition. They result in the following tags in SVG code:
|
||||
Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
|
||||
|
||||
![Accessibility options rendered inside SVG](img/accessibility-div-example.png)
|
||||
```html
|
||||
<svg
|
||||
aria-labelledby="chart-title-mermaid_382ee221"
|
||||
aria-describedby="chart-desc-mermaid_382ee221"
|
||||
aria-roledescription="flowchart-v2"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
width="100%"
|
||||
id="mermaid_382ee221"
|
||||
>
|
||||
<title id="chart-title-mermaid_382ee221">Big decisions</title>
|
||||
<desc id="chart-desc-mermaid_382ee221">Bob's Burgers process for making big decisions</desc>
|
||||
</svg>
|
||||
```
|
||||
|
||||
### Multi-line Accessibility title/description
|
||||
|
||||
You can also define the accessibility options in a multi-line format, where the keyword is followed by opening curly bracket `{` and then multiple lines, followed by a closing `}`.
|
||||
|
||||
`accTitle: My single line title value` (**_single line format_**)
|
||||
|
||||
vs
|
||||
|
||||
`accDescr: { My multi-line description of the diagram }` (**_multi-line format_**)
|
||||
|
||||
Let us look at it in the following example, with same flowchart:
|
||||
- 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
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: identify the big decision and then make the big decision."
|
||||
|
||||
```mermaid-example
|
||||
graph LR
|
||||
accTitle: Big decisions
|
||||
|
||||
graph LR
|
||||
accTitle: Bob's Burger's Making Big Decisions
|
||||
accDescr {
|
||||
My multi-line description
|
||||
of the diagram
|
||||
}
|
||||
|
||||
A[Hard] -->|Text| B(Round)
|
||||
B --> C{Decision}
|
||||
C -->|One| D[Result 1]
|
||||
|
||||
The official Bob's Burgers corporate processes that are used
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: identify the big decision and then make the big decision.
|
||||
}
|
||||
A[Identify Big Descision] --> B{Make Big Decision}
|
||||
B --> D[Be done]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
accTitle: Big decisions
|
||||
|
||||
graph LR
|
||||
accTitle: Bob's Burger's Making Big Decisions
|
||||
accDescr {
|
||||
My multi-line description
|
||||
of the diagram
|
||||
}
|
||||
|
||||
A[Hard] -->|Text| B(Round)
|
||||
B --> C{Decision}
|
||||
C -->|One| D[Result 1]
|
||||
|
||||
The official Bob's Burgers corporate processes that are used
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: identify the big decision and then make the big decision.
|
||||
}
|
||||
A[Identify Big Descision] --> B{Make Big Decision}
|
||||
B --> D[Be done]
|
||||
```
|
||||
|
||||
See in the code snippet above, the `accTitle` and `accDescr` are defined in the diagram definition. They result in the following tags in SVG code:
|
||||
Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
|
||||
|
||||
![Accessibility options rendered inside SVG](img/accessibility-div-example-2.png)
|
||||
|
||||
### Sample Code Snippet for other diagram types
|
||||
|
||||
#### Sequence Diagram
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
accTitle: My Sequence Diagram
|
||||
accDescr: My Sequence Diagram Description
|
||||
|
||||
Alice->>John: Hello John, how are you?
|
||||
John-->>Alice: Great!
|
||||
Alice-)John: See you later!
|
||||
```html
|
||||
<svg
|
||||
aria-labelledby="chart-title-mermaid_382ee221"
|
||||
aria-describedby="chart-desc-mermaid_382ee221"
|
||||
aria-roledescription="flowchart-v2"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
width="100%"
|
||||
id="mermaid_382ee221"
|
||||
>
|
||||
<title id="chart-title-mermaid_382ee221">Big decisions</title>
|
||||
<desc id="chart-desc-mermaid_382ee221">
|
||||
The official Bob's Burgers corporate processes that are used for making very, very big
|
||||
decisions. This is actually a very simple flow: identify the big decision and then make the big
|
||||
decision.
|
||||
</desc>
|
||||
</svg>
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
accTitle: My Sequence Diagram
|
||||
accDescr: My Sequence Diagram Description
|
||||
#### Sample Code Snippets for other diagram types
|
||||
|
||||
Alice->>John: Hello John, how are you?
|
||||
John-->>Alice: Great!
|
||||
Alice-)John: See you later!
|
||||
```
|
||||
|
||||
#### Class Diagram
|
||||
##### Class Diagram
|
||||
|
||||
```mermaid-example
|
||||
classDiagram
|
||||
@ -139,27 +190,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
Vehicle <|-- Car
|
||||
```
|
||||
|
||||
#### State Diagram
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
accTitle: My State Diagram
|
||||
accDescr: My State Diagram Description
|
||||
|
||||
s1 --> s2
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram
|
||||
accTitle: My State Diagram
|
||||
accDescr: My State Diagram Description
|
||||
|
||||
s1 --> s2
|
||||
|
||||
```
|
||||
|
||||
#### Entity Relationship Diagram
|
||||
##### Entity Relationship Diagram
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
@ -183,41 +214,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### User Journey Diagram
|
||||
|
||||
```mermaid-example
|
||||
journey
|
||||
accTitle: My User Journey Diagram
|
||||
accDescr: My User Journey Diagram Description
|
||||
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
journey
|
||||
accTitle: My User Journey Diagram
|
||||
accDescr: My User Journey Diagram Description
|
||||
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
|
||||
```
|
||||
|
||||
#### Gantt Chart
|
||||
##### Gantt Chart
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
@ -251,7 +248,45 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### Pie Chart
|
||||
##### Gitgraph
|
||||
|
||||
```mermaid-example
|
||||
gitGraph
|
||||
accTitle: My Gitgraph Accessibility Title
|
||||
accDescr: My Gitgraph Accessibility Description
|
||||
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
accTitle: My Gitgraph Accessibility Title
|
||||
accDescr: My Gitgraph Accessibility Description
|
||||
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
|
||||
```
|
||||
|
||||
##### Pie Chart
|
||||
|
||||
```mermaid-example
|
||||
pie
|
||||
@ -279,7 +314,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### Requirement Diagram
|
||||
##### Requirement Diagram
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
@ -321,40 +356,78 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### Gitgraph
|
||||
##### Sequence Diagram
|
||||
|
||||
```mermaid-example
|
||||
gitGraph
|
||||
accTitle: My Gitgraph Accessibility Title
|
||||
accDescr: My Gitgraph Accessibility Description
|
||||
sequenceDiagram
|
||||
accTitle: My Sequence Diagram
|
||||
accDescr: My Sequence Diagram Description
|
||||
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
Alice->>John: Hello John, how are you?
|
||||
John-->>Alice: Great!
|
||||
Alice-)John: See you later!
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
accTitle: My Sequence Diagram
|
||||
accDescr: My Sequence Diagram Description
|
||||
|
||||
Alice->>John: Hello John, how are you?
|
||||
John-->>Alice: Great!
|
||||
Alice-)John: See you later!
|
||||
```
|
||||
|
||||
##### State Diagram
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
accTitle: My State Diagram
|
||||
accDescr: My State Diagram Description
|
||||
|
||||
s1 --> s2
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
accTitle: My Gitgraph Accessibility Title
|
||||
accDescr: My Gitgraph Accessibility Description
|
||||
stateDiagram
|
||||
accTitle: My State Diagram
|
||||
accDescr: My State Diagram Description
|
||||
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
s1 --> s2
|
||||
|
||||
```
|
||||
|
||||
##### User Journey Diagram
|
||||
|
||||
```mermaid-example
|
||||
journey
|
||||
accTitle: My User Journey Diagram
|
||||
accDescr: My User Journey Diagram Description
|
||||
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
journey
|
||||
accTitle: My User Journey Diagram
|
||||
accDescr: My User Journey Diagram Description
|
||||
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
|
||||
```
|
||||
|
@ -4,83 +4,121 @@
|
||||
|
||||
Now with Mermaid library in much wider use, we have started to work towards more accessible features, based on the feedback from the community.
|
||||
|
||||
To begin with, we have added a new feature to Mermaid library, which is to support accessibility options, **Accessibility Title** and **Accessibility Description**.
|
||||
Adding 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).
|
||||
[Read more about Accessible Rich Internet Applications and the W3 standards.](https://www.w3.org/WAI/standards-guidelines/aria/)
|
||||
|
||||
This support for accessibility options is available for all the diagrams/chart types. Also, we have tired to keep the same format for the accessibility options, so that it is easy to understand and maintain.
|
||||
Mermaid 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)
|
||||
|
||||
## Defining Accessibility Options
|
||||
### aria-roledescription
|
||||
|
||||
### Single line accessibility values
|
||||
The [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.)
|
||||
|
||||
The diagram authors can now add the accessibility options in the diagram definition, using the `accTitle` and `accDescr` keywords, where each keyword is followed by `:` and the string value for title and description like:
|
||||
For 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-roledscription set to "stateDiagram". _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
|
||||
```html
|
||||
<svg aria-roledescription="stateDiagram" class="statediagram" xmlns="http://www.w3.org/2000/svg" width="100%" id="mermaid-1668720491568">
|
||||
```
|
||||
|
||||
- `accTitle: "Your Accessibility Title"` or
|
||||
- `accDescr: "Your Accessibility Description"`
|
||||
### Accessible Title and Description
|
||||
|
||||
**When these two options are defined, they will add a corresponding `<title>` and `<desc>` tag in the SVG.**
|
||||
Support 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.
|
||||
|
||||
Let us take a look at the following example with a flowchart diagram:
|
||||
The 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.
|
||||
|
||||
Here is HTML that is generated, showing that the SVG element is labelled by the accessible title (id = `chart-title-mermaid-1668725057758`)
|
||||
and described by the accessible description (id = `chart-desc-mermaid-1668725057758` );
|
||||
and the accessible title element (text = "This is the accessible title")
|
||||
and the accessible description element (text = "This is an accessible description").
|
||||
|
||||
_(Note that some of the SVG attributes and the SVG contents are omitted for clarity.)_
|
||||
|
||||
```html
|
||||
<svg aria-labelledby="chart-title-mermaid-1668725057758" aria-describedby="chart-desc-mermaid-1668725057758" xmlns="http://www.w3.org/2000/svg" width="100%" id="mermaid-1668725057758">
|
||||
<title id="chart-title-mermaid-1668725057758">This is the accessible title</title>
|
||||
<desc id="chart-desc-mermaid-1668725057758">This is an accessible description</desc>
|
||||
```
|
||||
|
||||
Details for the syntax follow.
|
||||
|
||||
|
||||
#### accessible title
|
||||
The **accessible title** is specified with the **accTitle** _keyword_, followed by a colon (`:`), and the string value for the title.
|
||||
The string value ends at the end of the line. (It can only be a single line.)
|
||||
|
||||
Ex: `accTitle: This is a single line title`
|
||||
|
||||
See [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.
|
||||
|
||||
|
||||
#### accessible description
|
||||
|
||||
An accessible description can be 1 line long (a single line) or many lines long.
|
||||
|
||||
The **single line accessible description** is specified with the **accDescr** _keyword_, followed by a colon (`:`), followed by the string value for the description.
|
||||
|
||||
Ex: `accDescr: This is a single line description.`
|
||||
|
||||
A **multiple line accessible description** _does not have a colon (`:`) after the accDescr keyword_ and is surrounded by curly brackets (`{}`).
|
||||
|
||||
Ex:
|
||||
```
|
||||
accDescr { The official Bob's Burgers corporate processes that are used
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: see the big decision and then make the big decision.}
|
||||
```
|
||||
|
||||
See [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.
|
||||
|
||||
|
||||
#### accTitle and accDescr Usage Examples
|
||||
|
||||
- Flowchart with the accessible title "Big Decisions" and the single-line accessible description "Bob's Burgers process for making big decisions"
|
||||
|
||||
```mermaid-example
|
||||
graph LR
|
||||
accTitle: Big decisions
|
||||
accDescr: Flow chart of the decision making process
|
||||
A[Hard] -->|Text| B(Round)
|
||||
B --> C{Decision}
|
||||
C -->|One| D[Result 1]
|
||||
graph LR
|
||||
accTitle: Big Decisions
|
||||
accDescr: Bob's Burgers process for making big decisions
|
||||
A[Identify Big Descision] --> B{Make Big Decision}
|
||||
B --> D[Be done]
|
||||
```
|
||||
|
||||
Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
|
||||
```html
|
||||
<svg aria-labelledby="chart-title-mermaid_382ee221" aria-describedby="chart-desc-mermaid_382ee221" aria-roledescription="flowchart-v2" xmlns="http://www.w3.org/2000/svg" width="100%" id="mermaid_382ee221">
|
||||
<title id="chart-title-mermaid_382ee221">Big decisions</title>
|
||||
<desc id="chart-desc-mermaid_382ee221">Bob's Burgers process for making big decisions</desc>
|
||||
|
||||
```
|
||||
|
||||
See in the code snippet above, the `accTitle` and `accDescr` are defined in the diagram definition. They result in the following tags in SVG code:
|
||||
|
||||
![Accessibility options rendered inside SVG](img/accessibility-div-example.png)
|
||||
|
||||
### Multi-line Accessibility title/description
|
||||
|
||||
You can also define the accessibility options in a multi-line format, where the keyword is followed by opening curly bracket `{` and then multiple lines, followed by a closing `}`.
|
||||
|
||||
`accTitle: My single line title value` (**_single line format_**)
|
||||
|
||||
vs
|
||||
|
||||
`accDescr: { My multi-line description of the diagram }` (**_multi-line format_**)
|
||||
|
||||
Let us look at it in the following example, with same flowchart:
|
||||
* 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
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: identify the big decision and then make the big decision."
|
||||
|
||||
```mermaid-example
|
||||
graph LR
|
||||
accTitle: Big decisions
|
||||
|
||||
graph LR
|
||||
accTitle: Bob's Burger's Making Big Decisions
|
||||
accDescr {
|
||||
My multi-line description
|
||||
of the diagram
|
||||
}
|
||||
The official Bob's Burgers corporate processes that are used
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: identify the big decision and then make the big decision.
|
||||
}
|
||||
A[Identify Big Descision] --> B{Make Big Decision}
|
||||
B --> D[Be done]
|
||||
```
|
||||
|
||||
A[Hard] -->|Text| B(Round)
|
||||
B --> C{Decision}
|
||||
C -->|One| D[Result 1]
|
||||
Here is the HTML generated for the SVG element: _(Note that some of the SVG attributes and the SVG contents are omitted for clarity.):_
|
||||
```html
|
||||
<svg aria-labelledby="chart-title-mermaid_382ee221" aria-describedby="chart-desc-mermaid_382ee221" aria-roledescription="flowchart-v2" xmlns="http://www.w3.org/2000/svg" width="100%" id="mermaid_382ee221">
|
||||
<title id="chart-title-mermaid_382ee221">Big decisions</title>
|
||||
<desc id="chart-desc-mermaid_382ee221">The official Bob's Burgers corporate processes that are used
|
||||
for making very, very big decisions.
|
||||
This is actually a very simple flow: identify the big decision and then make the big decision.</desc>
|
||||
|
||||
```
|
||||
|
||||
See in the code snippet above, the `accTitle` and `accDescr` are defined in the diagram definition. They result in the following tags in SVG code:
|
||||
|
||||
![Accessibility options rendered inside SVG](img/accessibility-div-example-2.png)
|
||||
#### Sample Code Snippets for other diagram types
|
||||
|
||||
### Sample Code Snippet for other diagram types
|
||||
|
||||
#### Sequence Diagram
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
accTitle: My Sequence Diagram
|
||||
accDescr: My Sequence Diagram Description
|
||||
|
||||
Alice->>John: Hello John, how are you?
|
||||
John-->>Alice: Great!
|
||||
Alice-)John: See you later!
|
||||
```
|
||||
|
||||
#### Class Diagram
|
||||
##### Class Diagram
|
||||
|
||||
```mermaid-example
|
||||
classDiagram
|
||||
@ -90,18 +128,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
Vehicle <|-- Car
|
||||
```
|
||||
|
||||
#### State Diagram
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
accTitle: My State Diagram
|
||||
accDescr: My State Diagram Description
|
||||
|
||||
s1 --> s2
|
||||
|
||||
```
|
||||
|
||||
#### Entity Relationship Diagram
|
||||
##### Entity Relationship Diagram
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
@ -114,25 +141,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### User Journey Diagram
|
||||
|
||||
```mermaid-example
|
||||
journey
|
||||
accTitle: My User Journey Diagram
|
||||
accDescr: My User Journey Diagram Description
|
||||
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
|
||||
```
|
||||
|
||||
#### Gantt Chart
|
||||
##### Gantt Chart
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
@ -150,7 +159,27 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### Pie Chart
|
||||
##### Gitgraph
|
||||
|
||||
```mermaid-example
|
||||
gitGraph
|
||||
accTitle: My Gitgraph Accessibility Title
|
||||
accDescr: My Gitgraph Accessibility Description
|
||||
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
|
||||
```
|
||||
|
||||
##### Pie Chart
|
||||
|
||||
```mermaid-example
|
||||
pie
|
||||
@ -165,7 +194,7 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### Requirement Diagram
|
||||
##### Requirement Diagram
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
@ -187,22 +216,44 @@ See in the code snippet above, the `accTitle` and `accDescr` are defined in the
|
||||
|
||||
```
|
||||
|
||||
#### Gitgraph
|
||||
##### Sequence Diagram
|
||||
|
||||
```mermaid-example
|
||||
gitGraph
|
||||
accTitle: My Gitgraph Accessibility Title
|
||||
accDescr: My Gitgraph Accessibility Description
|
||||
sequenceDiagram
|
||||
accTitle: My Sequence Diagram
|
||||
accDescr: My Sequence Diagram Description
|
||||
|
||||
commit
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge develop
|
||||
commit
|
||||
commit
|
||||
Alice->>John: Hello John, how are you?
|
||||
John-->>Alice: Great!
|
||||
Alice-)John: See you later!
|
||||
```
|
||||
|
||||
##### State Diagram
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
accTitle: My State Diagram
|
||||
accDescr: My State Diagram Description
|
||||
|
||||
s1 --> s2
|
||||
|
||||
```
|
||||
|
||||
|
||||
##### User Journey Diagram
|
||||
|
||||
```mermaid-example
|
||||
journey
|
||||
accTitle: My User Journey Diagram
|
||||
accDescr: My User Journey Diagram Description
|
||||
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
|
||||
```
|
||||
|
Loading…
x
Reference in New Issue
Block a user