fix(docs): render Mermaid diagrams with accessible titles and descriptions

[Bill Berry (WilliamBerryiii)]

Pull Request

Description

Mermaid fences on the documentation site shipped as syntax-highlighted source blocks rather than diagrams. Screen readers announced the raw Mermaid program — NVDA read the --> connection operator as "dash dash greater" — and the graphics carried no accessible name or description. This enables Mermaid rendering, gives every deployed diagram an authored title and description, and adds validation that keeps the corpus complete.

Automation here can prove that a title and description exist, render, and associate correctly. It cannot prove that they mean the right thing. The semantic pass is called out under Testing and remains open.

Rendering configuration and dependencies

Enabling the renderer was the prerequisite for everything else, since accessibility directives are inert while fences ship as code blocks.

• Set markdown.mermaid and registered @docusaurus/theme-mermaid as the first entry in themes in docusaurus.config.js, with a themeConfig.mermaid block binding the neutral and dark palettes to the site's existing color modes.
• Added two exact-pinned runtime dependencies: @docusaurus/theme-mermaid at 3.10.2 and mermaid at 11.16.1, matching the file's existing no-range convention.
• Regenerated package-lock.json with roughly 110 net-new transitive entries — the d3 family, cytoscape and its layout plugins, dagre-d3-es, roughjs, katex, marked, dompurify, and @mermaid-js/parser. Every entry resolves from the canonical public npm registry with integrity and license recorded.

Diagram metadata across the documentation corpus

• Authored accTitle and accDescr pairs across 44 documentation files, covering agent guides, architecture pages, ADRs, BRDs, PRDs, security documentation, and templates.
• The corpus now holds 64 fences, each with exactly one active title and description. Families in use are flowchart, legacy graph, stateDiagram-v2, journey, and erDiagram.
• Repaired four stateDiagram-v2 transition labels in agentic-workflows.md that used a semicolon. A semicolon terminates a Mermaid statement, so those labels failed to parse once rendering was live. The pre-repair form is now the parse-invalid negative control in the e2e spec.
• Refreshed ms.date on every edited file.

Validation

Three layers were added so that a diagram authored later cannot silently ship without metadata.

• validate-mermaid-accessibility.mjs discovers deployed pages through git ls-files, filters to the Docusaurus deployment boundary, extracts fences with matched markers, and requires exactly one active accTitle and accDescr per fence. Directives inside %% comments do not count. Failures report as file:line: message with a non-zero exit; --json emits the inventory for downstream consumers.
• validate-mermaid-accessibility.test.mjs covers the pure helpers with eight node:test cases, including the deployment-boundary predicate, unclosed-fence errors, multi-line accDescr flattening, and rejection of a commented-out title.
• mermaid-accessibility.spec.ts consumes that same --json inventory, so no second hand-maintained diagram list exists. It renders every fence in Chrome and asserts each SVG exposes role="graphics-document" with aria-labelledby and aria-describedby resolving to non-empty title and desc whose text matches the authored source. Two negative controls guard against passing by vacuity: a parse-invalid fixture the browser must reject, and a broken ARIA association the assertion helper must reject. Four representative routes then assert exact diagram counts, zero remaining pre code.language-mermaid blocks, and resolvable accessible names on the published pages.
• Wired test:mermaid-a11y into test and test:coverage, and excluded the native ESM validator test from Jest discovery so node --test, Jest, and Playwright each own a distinct layer.

Related Issue(s)

Fixes #2677

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Contributions MUST target models listed in the model catalog (scripts/linting/model-catalog.json) whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Execution Flow:

Output Artifacts:

Success Indicators:

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Automated validation run on this branch:

Check	Result
npm ci (docs/docusaurus)	Passed — 2053 packages, manifest and lockfile in sync
npm run test:mermaid-a11y	Passed — 8 native tests, 64 fences validated
npm run typecheck (docs/docusaurus)	Passed
npm run lint:a11y (docs/docusaurus)	Passed
npm run validate:local	26 of 27 checks passed; lint:md-links failed on three unrelated skill reference files
npm run validate:docs	Passed — docs lint, label registry, typecheck, 101 Jest tests, and the Mermaid source lane
npm run spell-check	Passed — 817 files, 0 issues
npm run lint:md-links	Skipped by explicit direction

The lint:md-links failures are in .github/skills/project-planning/security-planning/references/data-classification.md, .github/skills/rai/rai-standards/references/eu-ai-act.md, and .github/skills/rai/rai-standards/SKILL.md. None of those files is in this change set. Because validate:local is a sequential chain, that failure initially masked the 19 checks that follow it; those were run individually and all passed.

Diff-based assessment confirmed the four asserted route counts against source (Customization 1, Release Process 1, Agentic Workflows 3, SSSC Planner PRD 5) and corrected two figures that had gone stale against current main: the inventory lock moved from 65 to 64, and Release Process from 2 diagrams to 1, after main removed the Maturity Lifecycle state diagram. An Agentic Workflows route was added so stateDiagram stays covered at the route tier.

The full Playwright documentation lane is CI-owned and was not run locally on this branch.

Important

Manual assistive-technology verification has not been performed on this branch. The automated layers prove that every diagram renders as a named, described graphic with correct ARIA associations; they cannot prove that a title conveys the right purpose or that a description is equivalent to the diagram it replaces. A qualified accessibility reviewer should confirm the 64 title and description pairs, the complex-diagram prose equivalents, and representative screen-reader, forced-colors, and zoom behavior before this is considered conformant.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local (26 of 27 checks passed; lint:md-links failed on three files outside this change set)
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links (skipped by explicit direction)

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege (N/A — no files under scripts/security/ changed)

Both new scripts call execFileSync in argument-array form with no shell, so no command-injection surface exists, and the e2e spec invokes process.execPath rather than a PATH-resolved binary. File paths originate from git ls-files scoped to docs, are normalized, allowlist-filtered, and joined against a resolved repository root before any read. Neither script writes files, opens network connections, or reads credentials. Mermaid initializes with securityLevel: 'strict', and the browser bundle loads from local node_modules rather than a CDN. Both added dependencies are exact-pinned and resolve from the canonical public npm registry.

Additional Notes

The inventory lock and per-route diagram counts are deliberate but create a maintenance coupling: authoring or removing a Mermaid fence anywhere under docs/ requires updating expect(inventory).toHaveLength(64), and editing one of the four asserted pages requires updating its diagramCount. The expected family list is a closed set, so introducing a sequenceDiagram or gantt fence requires editing that assertion as well. The failure message names the offending file and line, so the required edit is discoverable from the test output.

One rough edge worth a follow-up: the validator's --json mode emits no JSON when failures exist, so a failing corpus surfaces in the e2e spec as a module-load exception during collection rather than a readable test failure.

[github-actions]

Dependency Review

The following issues were found:

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ✅ 0 package(s) with unknown licenses.
• ⚠️ 39 packages with OpenSSF Scorecard issues.

View full job summary

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.11%. Comparing base (68308dd) to head (c11b081).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2744      +/-   ##
==========================================
+ Coverage   83.08%   83.11%   +0.02%     
==========================================
  Files         183      183              
  Lines       33712    34109     +397     
  Branches       25       25              
==========================================
+ Hits        28010    28348     +338     
- Misses       5699     5758      +59     
  Partials        3        3              

Flag	Coverage Δ
docusaurus	89.92% <ø> (ø)
pester	83.87% <ø> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Eval Execution

⚠️ No eval summary was produced.

[Katrien De Graeve (katriendg)]

The Mermaid renderer, source validation, and SVG metadata associations are implemented well, and the focused validator passes all 64 fences. The review raised five findings, mostly medium and some may be considered optional. Leaving inline comments where possible.
Approving as I know you tackle each one. Thanks.