From bff16f7ea5c2d21c1b249bf4718be2ecc1aa4e79 Mon Sep 17 00:00:00 2001
From: Amy Qualls <aqualls@gitlab.com>
Date: Mon, 20 May 2024 19:09:57 +0000
Subject: [PATCH] Add fonts and a11y info to Mermaid diagrams

Make these diagrams prettier and more accessible. Configure the font
each one uses, and then set up accessible titles and descriptions
for each one.
---
 .../incident_management/status_page.md        |  4 +++
 doc/subscriptions/choosing_subscription.md    |  3 ++
 doc/tutorials/agile_sprint/index.md           |  4 +++
 doc/tutorials/make_first_git_commit/index.md  |  8 +++++
 doc/tutorials/scrum_events/index.md           | 29 ++++++++++++++-----
 doc/user/group/epics/index.md                 |  3 ++
 doc/user/group/planning_hierarchy/index.md    |  4 +++
 doc/user/group/saml_sso/group_sync.md         | 16 +++++-----
 doc/user/project/members/index.md             |  7 +++++
 9 files changed, 63 insertions(+), 15 deletions(-)

diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md
index a84d26618b562..144dede6a6854 100644
--- a/doc/operations/incident_management/status_page.md
+++ b/doc/operations/incident_management/status_page.md
@@ -113,7 +113,11 @@ and displays it to users, providing information about ongoing incidents without
 extra effort from your team:
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TB
+    accTitle: Understand your status page
+    accDescr: How GitLab fetches, formats, and displays incident data
+
     subgraph GitLab Instance
     issues(issue updates) -- trigger --> middleware(Background job: JSON generation)
     end
diff --git a/doc/subscriptions/choosing_subscription.md b/doc/subscriptions/choosing_subscription.md
index a332d1892484c..63c2b9a587ff8 100644
--- a/doc/subscriptions/choosing_subscription.md
+++ b/doc/subscriptions/choosing_subscription.md
@@ -42,7 +42,10 @@ The following chart should help you determine your subscription model. Select
 the list item to go to the respective help page.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TD
+  accTitle: My subscription
+  accDescr: Determine your subscription model and see its help page
 
 A(Is your user account on GitLab.com?)
 A --> B(Yes)
diff --git a/doc/tutorials/agile_sprint/index.md b/doc/tutorials/agile_sprint/index.md
index da4ae9fef0d35..2555bf738410f 100644
--- a/doc/tutorials/agile_sprint/index.md
+++ b/doc/tutorials/agile_sprint/index.md
@@ -50,7 +50,11 @@ disable the automated scheduling to
 Similar to membership, iterations cascade down your group, subgroup, and project hierarchy. If your team has multiple groups and projects, create the iteration cadence in the top-most shared group:
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TD
+    accTitle: Iteration cadence
+    accDescr: Identify the group you should create an iteration cadence in
+
     Group --> SubgroupA --> Project1
     Group --> SubgroupB --> Project2
     Group --> IterationCadence
diff --git a/doc/tutorials/make_first_git_commit/index.md b/doc/tutorials/make_first_git_commit/index.md
index e80cd6770d075..c95cabfe7f25d 100644
--- a/doc/tutorials/make_first_git_commit/index.md
+++ b/doc/tutorials/make_first_git_commit/index.md
@@ -35,7 +35,11 @@ Each time you push a change, Git records it as a unique *commit*. These commits
 the history of when and how a file changed, and who changed it.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph LR
+    accTitle: Repository commit history
+    accDescr: Flowchart showing linear changes to a repository history
+
     subgraph Repository commit history
     direction LR
     A(Author: Alex<br>Date: 3 Jan at 1PM<br>Commit message: Added sales figures<br> Commit ID: 123abc12) --->  B
@@ -53,7 +57,11 @@ of a repository are in a default branch. To make changes, you:
 1. When you're ready, *merge* your branch into the default branch.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 flowchart LR
+    accTitle: Use branches in Git
+    accDescr: The flow of creating, then using, a branch in Git
+
     subgraph Default branch
     A[Commit] --> B[Commit] --> C[Commit] --> D[Commit]
     end
diff --git a/doc/tutorials/scrum_events/index.md b/doc/tutorials/scrum_events/index.md
index ab4fcb2842184..a953987adca3f 100644
--- a/doc/tutorials/scrum_events/index.md
+++ b/doc/tutorials/scrum_events/index.md
@@ -49,6 +49,7 @@ standardize labels, boards, and iterations across multiple projects:
 flowchart TD
     accTitle: GitLab inheritance model diagram
     accDescr: Shows how groups, projects, issues, labels, milestones, iterations, tasks, and epics relate to one another in GitLab
+
     Group -->|Contains| Project
     Group -->|Contains| Epics
     Group -->|Contains| Labels
@@ -224,7 +225,11 @@ GitLab is extensible to support different flavors of backlog management.
 For this tutorial, we will structure our deliverables in the following way:
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 flowchart TD
+    accTitle: Deliverables structure
+    accDescr: Flowchart of features (epics) to job stories (issues) to implementation steps (tasks)
+
     Epic["Feature (Epic)"] --> Issue["Job Story (Issue)"]
     Issue --> Task["Implementation Step (Task)"]
 ```
@@ -258,10 +263,14 @@ Here's an example of breaking a feature into vertically sliced job stories based
 journey:
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 flowchart TD
-Epic["Epic: When using the application, I need to create an <br> account, so that I can use the application features"] --> Issue1["Issue: When creating my account, I need to specify my email address,<br> so that I can receive future updates from the application"]
-    Epic --> Issue2["Issue: When creating my account, I need to <br>specify a password, so that my account remains secure"]
-    Epic --> Issue3["Issue: When creating my account and entering the required info, I need to <br>finalize creating my account, so that I can log in"]
+  accTitle: Slicing a feature
+  accDescr: Use the end user's journey to identify slices of work to be completed in iterations
+
+Epic["Epic: When using the application,<br>I need to create an account,<br> so I can use the application features"] --> Issue1["Issue: When creating my account,<br> I need to specify my email address,<br> so I can receive future updates from the application"]
+    Epic --> Issue2["Issue: When creating my account,<br> I need to specify a password,<br> so my account remains secure"]
+    Epic --> Issue3["Issue: When creating my account<br> and entering the required info,<br> I need to finalize creating my account,<br> so I can log in"]
 ```
 
 You've taken the feature of an unmodified account sign-up for an application and broke it down into
@@ -275,12 +284,16 @@ After you have broken down a feature into stories, you can further break down th
 implementation steps:
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 flowchart TD
-  Issue1["Issue: When creating my account, I need to specify my email address,<br> so that I can receive future updates from the application"]
-  Issue1 --> Task2["Task: Backend - Validate email formatting"]
-  Issue1 --> Task3["Task: Backend - API endpoint to accept POST request from client"]
-  Issue1 --> Task4["Task: Frontend - Display email input"]
-  Issue1 --> Task5["Task: Frontend - Display error message when validation fails"]
+  accTitle: Break the story down further
+  accDescr: Split apart a story into smaller steps
+
+  Issue1["Issue: When creating my account,<br> I need to specify my email address,<br> so I can receive future updates from the application"]
+  Issue1 --> Task2["Task: Backend<br> Validate email formatting"]
+  Issue1 --> Task3["Task: Backend<br> API endpoint to accept<br> POST request from client"]
+  Issue1 --> Task4["Task: Frontend<br> Display email input"]
+  Issue1 --> Task5["Task: Frontend<br> Display error message when validation fails"]
 ```
 
 ### Set up a release planning board
diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md
index 4f6f960f59ce5..0eb12973dfed0 100644
--- a/doc/user/group/epics/index.md
+++ b/doc/user/group/epics/index.md
@@ -41,7 +41,10 @@ The possible relationships between epics and issues are:
 - An epic is the parent of one or more [child epics](manage_epics.md#multi-level-child-epics). Ultimate only.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TD
+accTitle: Epics and issues
+accDescr: How issues and child epics relate to parent epics
     Parent_epic --> Issue1
     Parent_epic --> Child_epic
     Child_epic --> Issue2
diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md
index 332b4daa3af8b..e7ac62a0823d7 100644
--- a/doc/user/group/planning_hierarchy/index.md
+++ b/doc/user/group/planning_hierarchy/index.md
@@ -28,7 +28,10 @@ portfolio management, see
 With epics, you can achieve the following hierarchy:
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TD
+accTitle: Hierarchies with epics
+accDescr: Use epics to link projects, issues, and groups
     Group_epic --> Project1_Issue1
     Group_epic --> Project1_Issue2
     Group_epic --> Project2_Issue1
@@ -48,6 +51,7 @@ Image below was generated with the following Mermaid code.
 Attached as an image because a rendered diagram doesn't look clear on the docs page.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 classDiagram
   direction TD
   class Epic
diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md
index 9328d68209056..93d0d73f83f31 100644
--- a/doc/user/group/saml_sso/group_sync.md
+++ b/doc/user/group/saml_sso/group_sync.md
@@ -142,7 +142,7 @@ group overage claim attribute in the SAML response. Then group memberships must
 The [Graph API endpoint](https://learn.microsoft.com/en-us/graph/api/user-list-transitivememberof?view=graph-rest-1.0&tabs=http#http-request) supports only a
 [user object ID](https://learn.microsoft.com/en-us/partner-center/find-ids-and-domain-names#find-the-user-object-id) or
 [userPrincipalName](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/plan-connect-userprincipalname#what-is-userprincipalname)
-as the [configured](../../../user/group/saml_sso/index.md#azure) Unique User Identifier (Name identifier) attribute. 
+as the [configured](../../../user/group/saml_sso/index.md#azure) Unique User Identifier (Name identifier) attribute.
 
 When the integration processes Group Sync, only Group Links configured with
 group unique identifiers (like `12345678-9abc-def0-1234-56789abcde`) are supported.
@@ -249,6 +249,7 @@ For example, in the following diagram:
   not yet signed in.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TB
    subgraph SAML users
       SAMLUserA[Sidney Jones]
@@ -274,6 +275,7 @@ graph TB
 ```
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TB
     subgraph GitLab users
       GitLabUserA[Sidney Jones]
@@ -283,9 +285,9 @@ graph TB
     end
 
    subgraph GitLab groups
-      GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"]
-      GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"]
-      GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"]
+      GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
+      GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
+      GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
    end
 
    GitLabGroupB --> |Member|GitLabUserA
@@ -308,9 +310,9 @@ graph TB
 
    subgraph GitLab groups after Alex Garcia signs in
       GitLabGroupA[Group A]
-      GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"]
-      GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"]
-      GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"]
+      GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
+      GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
+      GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
    end
 
    GitLabGroupB --> |Member|GitLabUserA
diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md
index 2f5fce72138e5..d197052d4c478 100644
--- a/doc/user/project/members/index.md
+++ b/doc/user/project/members/index.md
@@ -35,7 +35,11 @@ Indirect membership can be inherited, shared, or inherited shared.
 | [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of a parent of a group or project invited to the current group or project. |
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 flowchart RL
+  accTitle: Membership types
+  accDescr: Describes membership types and their inheritance
+
   subgraph Group A
     A(Direct member)
     B{{Shared member}}
@@ -397,7 +401,10 @@ In the following example, `User` is a:
 - Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`.
 
 ```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
 graph TD
+  accTitle: Diagram of group inheritance
+  accDescr: User inheritance, both direct and indirect through subgroups
   classDef user stroke:green,color:green;
 
   root --> subgroup --> subsubgroup
-- 
GitLab