[Audit] README Files - Mermaid Diagrams & Accessibility Review

[ashleyshaw]

Overview

Comprehensive audit of README files across the repository for Mermaid syntax validity, accessibility compliance, and documentation freshness.

In-Scope

• Discover all README files using reproducible commands
• Validate Mermaid syntax and render behaviour
• Assess Mermaid accessibility (accTitle, accDescr, contrast, readability)
• Identify stale README content and broken links

Out-of-Scope

• Non-README docs unless directly referenced by README fixes
• Large-scale content redesign not required for accuracy/a11y

Current Problems

1. Mermaid diagrams may contain syntax/rendering errors.
2. Accessibility metadata may be missing.
3. Content freshness is inconsistent.
4. Diagram behaviour in light/dark themes may be uneven.

Acceptance Criteria

• Full README inventory produced from reproducible discovery
• Mermaid syntax validation completed for all in-scope diagrams
• Accessibility gaps identified with concrete fixes
• Content freshness and link-health findings documented

Deliverables

• README inventory report
• Mermaid validation report
• Accessibility audit report
• Remediation issue set (if required)

Related Files

• **/README.md (repository-wide)
• docs/
• instructions/mermaid.instructions.md
• instructions/a11y.instructions.md

[linear-code]

LS-969

LS-1047

[github-actions]

🚫 This issue does not follow a required issue template and has been closed automatically.

Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)

Please reopen with one of the official templates:

• https://github.com/lightspeedwp/.github/issues/new/choose

If this was opened by automation, update the automation to preserve the template sections before creating the issue.

[ashleyshaw]

Reopened — this issue was incorrectly closed by the template-enforcement bot due to missing DoR/DoD sections (not a deliberate deprioritisation).

Status: Work already completed.
The audit and remediation work described here was delivered by the Wave 5 audit cycle (#652 parent, children #667, #668, #669, #670). The automated validators (validate:mermaid-syntax, validate:mermaid-accessibility, validate:mermaid-contrast) were added in PR #977 and the full WCAG colour palette sweep was completed in PR #982.

Closing as completed.

---

Generated by Claude Code