feat(mermaid): WCAG 2.2 AA colour contrast validation and updated diagram standards

.github/ISSUE_TEMPLATE/README.md

@@ -3,7 +3,7 @@ title: "Issue Templates Directory"
 description: "Standardized issue templates for the LightSpeedWP organization. Templates for bugs, features, documentation, and custom issues with automation integration."
 name: "Issue Templates"
 file_type: documentation
-version: v1.5
+version: v1.7
 last_updated: "2026-06-18"
 created_date: "2025-10-20"
 authors: ["LightSpeed Team"]
@@ -46,8 +46,10 @@ For advanced usage, see the [Issue Template Index](./README.md) and individual t
 ## 🗂️ Issue Template Workflow
 
 ```mermaid
+---
 accTitle: Issue template workflow
-accDescr: Shows how users select an issue template, auto-populated fields flow into issue creation, and automation routes the issue to labelling, project, and notification steps.
+accDescr: Shows the flow from user selecting a template through auto-labeling, agent processing, and routing to project boards.
+---
 flowchart TD
     A[User Creates Issue] --> B{Select Template}
     B -->|Bug Report| C[Bug Template]
@@ -61,15 +63,15 @@ flowchart TD
     F --> G
 
     G --> H[Issue Creation]
-    H --> I[Agent Processing]
+    H --> I[⚙️ Agent Processing]
 
-    I --> J[Auto-labeling]
+    I --> J[🏷️ Auto-labeling]
     I --> K[Issue Type Assignment]
-    I --> L[Project Board Assignment]
+    I --> L[📊 Project Board]
     I --> M[Notification Routing]
 
     N[Template Sync] --> O[All Org Repos]
-    P[Automation Agents] --> I
+    P[🤖 Automation Agents] --> I
     Q[Label System] --> J
     R[Project Management] --> L
 

.github/prompts/update-mermaid-diagrams.prompt.md

@@ -1,7 +1,7 @@
 ---
 file_type: "prompt"
 title: "Update Mermaid Diagrams"
-description: "Refresh Mermaid diagrams across the repository with WCAG 2.2 AA contrast, explicit accessibility metadata, and current repository standards."
+description: "Refresh Mermaid diagrams across the repository or targeted paths with WCAG 2.2 AA colour contrast, updated content, and current standards."
 mode: "agent"
 tools: ["read", "edit", "search", "shell"]
 tags: ["mermaid", "documentation", "a11y", "wcag", "colour-contrast", "readme"]
@@ -10,20 +10,19 @@ last_updated: "2026-06-18"
 
 # Update Mermaid Diagrams
 
-Refresh Mermaid diagrams across the repository to conform with the current standards in `instructions/mermaid.instructions.md`.
+Refresh Mermaid diagrams across the repository to conform with the v2.0 standards in `instructions/mermaid.instructions.md`.
 
 ## Standards Reference
 
-- **Instructions**: `instructions/mermaid.instructions.md` - required structure, palette, and accessibility rules
-- **Validator**: `scripts/validation/validate-mermaid-accessibility.js` - accTitle / accDescr checks
-- **Validator**: `scripts/validation/validate-mermaid-colour-contrast.js` - WCAG 2.2 AA colour contrast checks
-- **Workflow**: `.github/workflows/readme-audit.yml` and `.github/workflows/readme-update.yml` - audit and update automation
+- **Instructions**: `instructions/mermaid.instructions.md` — v2.0 approved palette, required structure, emoji vocabulary
+- **Validator**: `scripts/validation/validate-mermaid-colour-contrast.js` — WCAG 2.2 AA contrast checker
+- **Workflow**: `.github/workflows/validate-mermaid-pr.yml` — PR enforcement
 
 ## What to Fix in Every Diagram
 
 ### 1. Required accessibility header block
 
-Every `\`\`\`mermaid` block must open with an accessibility header before the diagram type:
+Every `\`\`\`mermaid` block must open with a YAML header before the diagram type:
 
 ```text
 ---
@@ -47,19 +46,19 @@ accDescr {
 
 Remove any legacy inline `accTitle` / `accDescr` attributes that appear after the diagram type line.
 
-### 2. Approved colour palette
+### 2. Approved colour palette — replace ALL old `style` declarations
 
-Replace every `style` or `classDef` declaration that sets a `fill:` colour with an approved triple. Choose the role that best matches the node's meaning:
+Replace every old `style X fill:#colour` (single property) with an approved triple. Choose the role that best matches the node's meaning:
 
 | Role | fill | color | stroke |
 |------|------|-------|--------|
-| Information | `#dbeafe` | `#1e3a5f` | `#1e3a5f` |
-| Success | `#dcfce7` | `#14532d` | `#14532d` |
-| Warning | `#fef3c7` | `#4a2c00` | `#b45309` |
-| Error / Alert | `#fee2e2` | `#7f1d1d` | `#b91c1c` |
-| Documentation | `#f3e8ff` | `#3b0764` | `#7e22ce` |
-| Neutral | `#f1f5f9` | `#0f172a` | `#334155` |
-| Highlight | `#ecfdf5` | `#064e3b` | `#059669` |
+| Information (entry points, primary) | `#dbeafe` | `#1e3a5f` | `#1e3a5f` |
+| Success (outputs, completed) | `#dcfce7` | `#14532d` | `#14532d` |
+| Warning (caution, external) | `#fef3c7` | `#4a2c00` | `#b45309` |
+| Error / Alert (failure, blockers) | `#fee2e2` | `#7f1d1d` | `#b91c1c` |
+| Documentation (specs, instructions, AI) | `#f3e8ff` | `#3b0764` | `#7e22ce` |
+| Neutral (connectors, supporting) | `#f1f5f9` | `#0f172a` | `#334155` |
+| Highlight (automation, key actions) | `#ecfdf5` | `#064e3b` | `#059669` |
 
 Example:
 
@@ -71,7 +70,7 @@ style C fill:#dcfce7,color:#14532d,stroke:#14532d
 
 ### 3. Diagram type and direction
 
-- Prefer `flowchart` over `graph`.
+- Prefer `flowchart` over `graph` (current Mermaid standard).
 - Always specify direction: `flowchart LR`, `flowchart TD`, etc.
 
 ### 4. Emoji vocabulary
@@ -93,29 +92,28 @@ Update diagram content to reflect the current codebase. Check:
 
 ## Process
 
-1. Run the Mermaid validators to identify all affected files:
+1. Run the contrast validator to get the full list of affected files:
 
    ```bash
-   npm run validate:mermaid-accessibility
    npm run validate:mermaid-contrast
    ```
 
 2. For each file with findings, open it and apply the fixes above.
 
-3. After fixing all files, run the full Mermaid suite:
+3. After fixing all files, run the full suite to confirm zero failures:
 
    ```bash
    npm run validate:mermaid
    ```
 
-4. If a documentation file does not yet contain a diagram, only add one when the visual adds clear value over prose.
+4. If adding new diagrams to README files that don't have one, ensure the diagram accurately represents what that file/folder contains.
 
 ## Validation Gate
 
-All Mermaid checks must pass before merging:
+All three checks must pass before committing:
 
 ```bash
-npm run validate:mermaid-syntax
-npm run validate:mermaid-accessibility
-npm run validate:mermaid-contrast
+npm run validate:mermaid-syntax        # diagram type, direction, bracket matching
+npm run validate:mermaid-accessibility # accTitle and accDescr present
+npm run validate:mermaid-contrast      # WCAG 2.2 AA colour contrast
 ```