Accessibility issue: Mermaid diagrams render as source code and expose arrow syntax to screen readers

[jkim323]

Summary

Mermaid diagrams on the HVE Core documentation site render as syntax-highlighted source code rather than diagrams with accessible titles and descriptions.

During manual NVDA testing of Release Process → How Releases Work, NVDA announced the Mermaid connection operator --> using punctuation terms such as "dash dash greater." It did not announce the content as a release workflow or communicate the connections between its stages.

This was discovered during the manual assistive-technology pass for #2566, but the affected page and Docusaurus Mermaid configuration are not part of that pull request's origin/main...HEAD diff.

Steps to reproduce

1. Build and serve the Docusaurus documentation site.
2. Start NVDA and enable browse mode.
3. Open /hve-core/docs/contributing/release-process.
4. Navigate to How Releases Work.
5. Read the diagram content.
6. Repeat under Maturity Lifecycle.

Observed behavior

• Each Mermaid fence renders as a <pre><code class="language-mermaid"> block.
• Edge exposes the raw Mermaid program through the accessibility tree.
• NVDA reads operators such as --> as punctuation, including "greater."
• The diagrams have no computed accessible diagram title or description.
• The numbered steps following How Releases Work provide a detailed textual sequence, but users encounter the raw Mermaid source first.

The repository currently contains 69 Mermaid fence occurrences, so other documentation pages may have the same behavior.

Expected behavior

Mermaid fences render as diagrams. Each meaningful diagram exposes a concise accessible title and description, and complex relationships have equivalent textual content. NVDA announces the diagram's purpose instead of Mermaid operators.

Environment

• Windows 11
• Microsoft Edge 151.0.4129.72
• NVDA 2026.1.1
• NVDA browse mode
• Local Docusaurus production build

Root cause

• docs/docusaurus/docusaurus.config.js does not enable Mermaid rendering or register the Docusaurus Mermaid theme.
• docs/docusaurus/package.json does not declare @docusaurus/theme-mermaid.

Do not replace --> with a Unicode arrow. The operator is valid Mermaid syntax; the defect is that the source is published rather than rendered.

Proposed remediation

1. Add @docusaurus/theme-mermaid at the same version as the existing Docusaurus packages.
2. Enable Mermaid in the Docusaurus Markdown configuration and register the theme.
3. Add Mermaid accTitle and accDescr directives to both diagrams in docs/contributing/release-process.md.
4. Introduce each diagram with prose explaining its purpose.
5. Keep the numbered release steps as detailed equivalent content.
6. Audit the remaining Mermaid fences for accessible titles, descriptions, and equivalent content.
7. Add production-build regression coverage that detects intended Mermaid diagrams rendered as raw language-mermaid code.

Acceptance criteria

• Mermaid rendering is enabled in the Docusaurus site.
• @docusaurus/theme-mermaid matches the version of the other Docusaurus packages.
• Intended diagrams do not appear as raw pre code.language-mermaid content in the production build.
• How Releases Work has an accessible title and description.
• Maturity Lifecycle has an accessible title and description.
• The numbered release steps remain available as detailed equivalent content.
• NVDA no longer reads --> as "dash dash greater" when navigating these diagrams.
• NVDA announces meaningful diagram titles and descriptions.
• Diagrams remain legible in light, dark, forced-colors, and supported zoom states.
• Automated coverage verifies that Mermaid rendering is active.
• A broader audit identifies Mermaid diagrams without equivalent textual content.
• Docusaurus build, unit tests, accessibility checks, and Playwright tests pass.
• A qualified accessibility reviewer confirms the result before closure.

Accessibility assessment

• Manual observation: raw Mermaid source and arrow operators are announced instead of a named diagram.
• Candidate criteria: WCAG 2.2 SC 1.1.1, Non-text Content, and SC 1.3.1, Information and Relationships.

The criterion mapping and final conformance result remain subject to qualified accessibility review.