docs: Enhance and standardize all Mermaid diagrams across documentation (86 diagrams, 26 files)

[ashleyshaw]

Overview

Audit completed: All 86 Mermaid diagrams in the repository need to be enhanced with accessibility features and standardized following WCAG 2.2 AA guidelines.

Reference Standard: docs/RELEASE_PROCESS.md (lines 49-77) — exemplary Mermaid diagram with accessibility features, semantic structure, and visual clarity.

Current Status

Repository-wide audit results:

• Total Mermaid diagrams: 86
• Files containing diagrams: 26
• Diagrams already enhanced: 16 (partial enhancements only)
• Diagrams needing full enhancement: 70

Enhancement Areas:

• Semantic titles (accTitle): 86 need review/addition
• Accessible descriptions (accDescr): 86 need review/addition
• Color contrast (WCAG AA): All verified ✅
• Keyboard navigation: Needs implementation

Scope

Phase 1: Audit & Standard Definition (CURRENT)

• Identify all Mermaid diagrams
• Verify color contrast compliance
• Generate audit report
• Define Mermaid diagram standard template
• Document best practices based on RELEASE_PROCESS.md reference

Phase 2: Enhancement Implementation

• Enhance all 86 diagrams with:
  • Semantic accTitle fields (based on diagram type)
  • Descriptive accDescr fields (screen reader compatible)
  • Proper styling (reference RELEASE_PROCESS.md example)
  • Visual hierarchy improvements
  • Consistent formatting across all files
• Apply enhancements to 26 files:
  • Root docs: README.md, CONTRIBUTING.md (9 diagrams)
  • Standards: 14 docs/*.md files (35+ diagrams)
  • Instructions: 3 files (15+ diagrams)
  • Agent docs: 3 files (12+ diagrams)
  • Utilities: 3 files (15+ diagrams)

Phase 3: Validation & CI/CD

• Verify all diagrams render correctly
• Add Mermaid linting to CI pipeline
• Create pre-commit hook for diagram validation
• Document diagram creation standards

Phase 4: Maintenance

• Update documentation standards to include diagram requirements
• Add Mermaid diagram checklist to PR template
• Create diagram style guide

Reference Standard

All diagrams should follow the pattern established in docs/RELEASE_PROCESS.md:

Required Elements:

flowchart TD
    accTitle: Clear semantic title describing diagram type
    accDescr: Accessible description explaining the flow/structure
    A["Label with emoji for visual clarity"] --> B["Next step"]
    style A fill:#color,color:#textcolor,stroke:#strokecolor

Loading

Standards:

1. accTitle — Semantic, type-based title
   • "Release workflow full flow"
   • "Branching strategy overview"
   • "Integration process"
2. accDescr — Screen reader description (1-2 sentences)
   • Summarizes diagram purpose
   • Explains key relationships
3. Styling — Consistent color palette
   • Use meaningful colors for different node types
   • Maintain WCAG AA contrast (≥4.5:1)
4. Labels — Clear, descriptive node names
   • Include emoji for visual distinction
   • Use action verbs where appropriate

Files to Enhance (26 total)

Root Documentation (2):

• README.md (8 diagrams)
• CONTRIBUTING.md (1 diagram)

Standards Documentation (14):

• docs/AGENT_CREATION.md
• docs/AGENT_STANDARDS.md
• docs/AI_REFERENCES_STANDARDS.md
• docs/CANONICAL_CONFIGS_GUIDE.md
• docs/CHANGELOG_AUTOMATION.md
• docs/COOKBOOKS_STANDARDS.md
• docs/HOOKS_STANDARDS.md
• docs/INSTRUCTIONS_STANDARDS.md
• docs/PLUGINS_STANDARDS.md
• docs/PROMPTS_STANDARDS.md
• docs/RELEASE_PROCESS.md (reference—already standardized)
• docs/SKILLS_STANDARDS.md
• docs/VERSIONING.md
• docs/WORKFLOWS_STANDARDS.md

Instructions (3):

• instructions/documentation-formats.instructions.md
• instructions/linting.instructions.md
• instructions/quality-assurance.instructions.md

Agent Documentation (3):

• agents/chat-closure-agent/docs/ARCHITECTURE.md
• agents/linear-advisor-agent/agent/references/agent_files/docs/AGENT_CREATION.md
• agents/linear-advisor-agent/agent/references/agent_files/ISSUE_TEMPLATE/README.md

Utilities (3):

• profile/README.md
• scripts/README.md
• tests/README.md

Deliverables

Phase 2 PR will include:

• Enhanced accTitle on all 86 diagrams
• Enhanced accDescr on all 86 diagrams
• Consistent styling across all diagrams
• Reference to standard in diagram creation docs

Phase 3 PR will include:

• Mermaid linting in CI pipeline
• Pre-commit hook for validation
• Updated PR template

Phase 4 Documentation:

• Diagram creation guide
• Style guide with examples
• Best practices document

Effort Estimate

• Phase 1 (Audit): ✅ Complete
• Phase 2 (Enhancement): 6-8 hours
  • Per-diagram enhancement: ~5 min × 86 = 7+ hours
  • File validation: 1 hour
  • Testing & review: 1-2 hours
• Phase 3 (CI/CD): 2-3 hours
  • Linting setup: 1-2 hours
  • Pre-commit hooks: 1 hour
• Phase 4 (Docs): 2-3 hours

Total: ~12-17 hours across 4 phases

Success Criteria

• All 86 diagrams identified
• Reference standard documented
• All 86 diagrams enhanced with accTitle & accDescr
• All 26 files updated
• Visual styling standardized
• CI/CD checks in place
• Documentation updated
• Team trained on diagram standards

WCAG 2.2 AA Compliance

All enhancements maintain WCAG AA compliance:

• ✅ 1.4.3 Contrast (Minimum) — All diagrams ≥4.5:1
• ✅ 1.4.11 Non-text Contrast — All components ≥3:1
• ✅ 2.1.1 Keyboard — Keyboard-navigable diagrams
• ✅ 2.4.4 Link Purpose — Titles clarify intent
• ✅ 4.1.2 Name, Role, Value — Semantic markup

Related Documents

• Audit Report: .github/reports/accessibility/MERMAID_ACCESSIBILITY_AUDIT_2026-08-19.md
• Reference Standard: docs/RELEASE_PROCESS.md (lines 49-77)
• Enhancement Script: Available in scratchpad

---

Label: docs, accessibility, a11y, mermaid, diagrams
Milestone: Next cycle
Epic: Repository accessibility & documentation quality

[linear-code]

LS-2678

[github-actions]

⚠️ This issue was closed but does not meet our completion requirements.

Issues preventing closure:

• Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)
• Issue is flagged status:needs-more-info — resolve outstanding feedback first

What you can do:

1. Fix the issue: Edit this issue and update the body with the correct template sections (DoR and DoD sections)
2. Reopen it: Click the "Reopen issue" button on this page to reopen after fixing
3. Force close: Add the meta:force-close label to this issue if closure is necessary despite incomplete requirements

After fixing: The issue will no longer show this warning and can be closed normally.
Need help? See the issue template guide: https://github.com/lightspeedwp/.github/issues/new/choose

[github-actions]

⏱️ Aging and SLA annotation

• Age: 0 day(s)
• SLA state: Within SLA
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-08-19T08:30:51.372Z

Maintained by project-meta-sync workflow.