diff --git a/.github/workflows/validate-mermaid-pr.yml b/.github/workflows/validate-mermaid-pr.yml
new file mode 100644
index 00000000..89969b6e
--- /dev/null
+++ b/.github/workflows/validate-mermaid-pr.yml
@@ -0,0 +1,204 @@
+name: Validate Mermaid Diagrams
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    paths:
+      - "**/*.md"
+      - "**/*.mdx"
+  push:
+    branches-ignore:
+      - main
+      - develop
+    paths:
+      - "**/*.md"
+      - "**/*.mdx"
+
+concurrency:
+  group: mermaid-validate-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Mermaid Diagram Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Identify changed Markdown files
+        id: changed
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="${{ github.event.pull_request.base.sha }}"
+            HEAD="${{ github.event.pull_request.head.sha }}"
+          else
+            BASE="${{ github.event.before }}"
+            HEAD="${{ github.sha }}"
+          fi
+
+          # Fall back to HEAD~1 when base is the null SHA (first push on a branch)
+          if [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
+            BASE="HEAD~1"
+          fi
+
+          CHANGED=$(git diff --name-only "$BASE" "$HEAD" -- '*.md' '*.mdx' 2>/dev/null || git diff --name-only HEAD~1 HEAD -- '*.md' '*.mdx')
+          echo "files=$CHANGED" >> "$GITHUB_OUTPUT"
+
+          if [ -z "$CHANGED" ]; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+            echo "Changed Markdown files:"
+            echo "$CHANGED"
+          fi
+
+      - name: Check for Mermaid diagrams in changed files
+        id: has_diagrams
+        if: steps.changed.outputs.has_changes == 'true'
+        run: |
+          CHANGED="${{ steps.changed.outputs.files }}"
+          HAS_MERMAID=false
+          for f in $CHANGED; do
+            if [ -f "$f" ] && grep -q '```mermaid' "$f"; then
+              HAS_MERMAID=true
+              break
+            fi
+          done
+          echo "result=$HAS_MERMAID" >> "$GITHUB_OUTPUT"
+
+      - name: Skip — no Mermaid diagrams in changed files
+        if: steps.has_diagrams.outputs.result != 'true'
+        run: echo "No Mermaid diagrams found in changed files — skipping validation."
+
+      - name: Validate diagram syntax
+        id: syntax
+        if: steps.has_diagrams.outputs.result == 'true'
+        run: npm run validate:mermaid-syntax
+        continue-on-error: true
+
+      - name: Validate accessibility (accTitle / accDescr)
+        id: accessibility
+        if: steps.has_diagrams.outputs.result == 'true'
+        run: npm run validate:mermaid-accessibility
+        continue-on-error: true
+
+      - name: Validate colour contrast (WCAG 2.2 AA)
+        id: contrast
+        if: steps.has_diagrams.outputs.result == 'true'
+        run: npm run validate:mermaid-contrast
+        continue-on-error: true
+
+      - name: Collect results
+        id: results
+        if: steps.has_diagrams.outputs.result == 'true'
+        run: |
+          SYNTAX="${{ steps.syntax.outcome }}"
+          A11Y="${{ steps.accessibility.outcome }}"
+          CONTRAST="${{ steps.contrast.outcome }}"
+
+          echo "syntax_ok=$([ "$SYNTAX" = "success" ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          echo "a11y_ok=$([ "$A11Y" = "success" ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          echo "contrast_ok=$([ "$CONTRAST" = "success" ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+
+          if [ "$SYNTAX" = "success" ] && [ "$A11Y" = "success" ] && [ "$CONTRAST" = "success" ]; then
+            echo "all_passed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "all_passed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post PR comment with results
+        if: github.event_name == 'pull_request' && steps.has_diagrams.outputs.result == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const syntaxOk    = '${{ steps.results.outputs.syntax_ok }}'   === 'true';
+            const a11yOk      = '${{ steps.results.outputs.a11y_ok }}'     === 'true';
+            const contrastOk  = '${{ steps.results.outputs.contrast_ok }}' === 'true';
+            const allPassed   = syntaxOk && a11yOk && contrastOk;
+
+            const icon  = (ok) => ok ? '✅' : '❌';
+            const label = (ok) => ok ? 'Passed' : 'Failed';
+
+            const body = [
+              '## 🎨 Mermaid Diagram Validation',
+              '',
+              allPassed
+                ? '✅ All Mermaid diagram checks passed.'
+                : '❌ One or more Mermaid diagram checks failed. Review the job logs and fix before merging.',
+              '',
+              '| Check | Result |',
+              '|-------|--------|',
+              `| ${icon(syntaxOk)} Syntax (diagram type, direction, bracket matching) | ${label(syntaxOk)} |`,
+              `| ${icon(a11yOk)} Accessibility (\`accTitle\` / \`accDescr\` present) | ${label(a11yOk)} |`,
+              `| ${icon(contrastOk)} Colour contrast (WCAG 2.2 AA ≥ 4.5:1) | ${label(contrastOk)} |`,
+              '',
+              allPassed
+                ? ''
+                : '**Fix guidance:** See [`instructions/mermaid.instructions.md`](./instructions/mermaid.instructions.md) for the approved colour palette and required structure.',
+            ].join('\n');
+
+            // Find and update an existing comment if present
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.find(
+              (c) => c.user.type === 'Bot' && c.body.includes('Mermaid Diagram Validation')
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: Fail if any check failed
+        if: steps.results.outputs.all_passed == 'false'
+        run: |
+          echo "One or more Mermaid validation checks failed."
+          echo "  Syntax:     ${{ steps.syntax.outcome }}"
+          echo "  A11y:       ${{ steps.accessibility.outcome }}"
+          echo "  Contrast:   ${{ steps.contrast.outcome }}"
+          exit 1
+
+      - name: Upload validation reports
+        if: always() && steps.has_diagrams.outputs.result == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: mermaid-validation-reports-${{ github.run_number }}
+          path: |
+            .github/reports/mermaid-validation-report.md
+            .github/reports/mermaid-accessibility-report.md
+            .github/reports/mermaid/colour-contrast-report-*.md
+          if-no-files-found: ignore
+          retention-days: 14
diff --git a/instructions/mermaid.instructions.md b/instructions/mermaid.instructions.md
index 121cdb13..e8113cba 100644
--- a/instructions/mermaid.instructions.md
+++ b/instructions/mermaid.instructions.md
@@ -1,109 +1,255 @@
 ---
 file_type: "instructions"
 title: "Mermaid Diagram Instructions"
-description: "How to design, create, style, and validate Mermaid diagrams for documentation and architecture visualization"
+description: "Design, accessibility, colour contrast, and validation standards for all Mermaid diagrams across LightSpeed repositories"
 scope: "repo-local"
-version: "v1.0"
-last_updated: "2026-05-29"
+version: "v2.0"
+last_updated: "2026-06-18"
 owners: ["LightSpeed Team"]
-tags: ["mermaid", "diagrams", "documentation", "a11y", "visuals", "architecture"]
+tags: ["mermaid", "diagrams", "documentation", "a11y", "wcag", "colour-contrast", "visuals", "architecture"]
 applyTo: ["**/*.md"]
 status: "active"
 ---
 
 # Mermaid Diagram Instructions
 
-Use Mermaid diagrams to visualize processes, architectures, and workflows. Create clear, accessible diagrams that enhance documentation.
+All Mermaid diagrams must be visually clear, accessible (WCAG 2.2 AA), and consistent. Follow every rule in this file. The validation workflow enforces them automatically on every PR.
 
-## Diagram Types
+---
+
+## When to Include a Diagram
 
-### Flowchart
+Include at least one Mermaid diagram in any README or documentation file that describes:
 
-- Show decision trees and process flows
-- Use for workflows and conditionals
-- Example: Issue triage process, PR workflow
+- A multi-step process or workflow
+- Component relationships or architecture
+- A state machine or lifecycle
+- Data flow between systems
+- A timeline or schedule
 
-### Sequence Diagram
+Do **not** force a diagram into a file where a simple list or paragraph is clearer. One well-chosen diagram adds more value than several weak ones.
+
+---
 
-- Show interactions between systems
-- Use for API calls, message flows
-- Example: Authentication flow, deployment sequence
+## Required Structure
 
-### State Diagram
+Every Mermaid block **must** include an accessibility header block placed immediately after the opening ` ```mermaid ` fence and before the diagram type declaration:
 
-- Show state transitions
-- Use for status workflows, lifecycle
-- Example: Issue status flow, deployment states
+```text
+```mermaid
+---
+accTitle: Short accessible title (max 80 chars)
+accDescr: Single-sentence description for simple diagrams
+---
+flowchart LR
+    ...
+```
 
-### Gantt Chart
+```
 
-- Show timelines and dependencies
-- Use for release schedules, project planning
-- Example: Sprint timeline, milestone calendar
+For complex diagrams use the block form:
 
-### Entity Relationship Diagram
+```text
+```mermaid
+---
+accTitle: Complex workflow title
+accDescr {
+  Multi-sentence description explaining what the diagram shows, the key
+  relationships, and the direction of flow. Write for screen-reader users
+  who cannot see the visual diagram.
+}
+---
+flowchart TD
+    ...
+```
 
-- Show data relationships
-- Use for schema documentation
-- Example: Database schema, data structures
+```
 
-## Design Guidelines
+**Rules:**
+- `accTitle` is mandatory on every diagram — no exceptions.
+- `accDescr` is mandatory on every diagram — no exceptions.
+- Place the `---` header block first, before `flowchart`, `graph`, `sequenceDiagram`, etc.
+- Do not duplicate `accTitle` / `accDescr` as inline attributes after the diagram type line (older style). Use only the header block.
 
-### Simplicity
+---
 
-- One concept per diagram
-- Limit to 5-7 nodes/boxes when possible
-- Avoid unnecessary complexity
-- Group related elements
+## Diagram Types — When to Use Each
 
-### Clarity
+| Type | Use for | Example |
+|------|---------|---------|
+| `flowchart LR` | Left-to-right pipelines, data flows | CI/CD pipeline, API request flow |
+| `flowchart TD` | Top-down hierarchies, decision trees | Component tree, issue triage |
+| `sequenceDiagram` | System interactions over time | Auth flow, webhook delivery |
+| `stateDiagram-v2` | State machines, lifecycle transitions | Issue status, deployment states |
+| `erDiagram` | Data relationships and schema | Database schema, data models |
+| `gantt` | Timelines, release schedules | Sprint plan, milestone calendar |
+| `pie` | Proportional composition | Label distribution, coverage breakdown |
+| `mindmap` | Topic hierarchies and associations | Feature exploration, knowledge maps |
 
-- Use descriptive labels
-- Avoid abbreviations unless standard
-- Consistent node naming
-- Clear arrow direction
+**Prefer `flowchart` over `graph`** — `flowchart` is the current Mermaid standard and supports more styling features. Only use `graph` if you need legacy compatibility.
 
-### Accessibility
+**Always specify direction** — `flowchart LR`, `flowchart TD`, etc. Never leave the direction implicit.
 
-- Text-based, not image-only
-- Descriptive alt text below diagram
-- High contrast between elements
-- Avoid color-only information
+---
 
-## Styling
+## Colour Palette — Approved WCAG AA Pairs
 
-Use Mermaid theme variables for consistency:
+Every `style` declaration **must** set `fill`, `color`, and `stroke` together. Never set `fill` alone — Mermaid's theme may override the text colour to white or another low-contrast value depending on the viewer's GitHub theme (light/dark mode).
 
+All pairs below are pre-verified to meet **WCAG 2.2 AA 4.5:1** normal-text contrast in every GitHub theme:
+
+| Role | `fill` | `color` | `stroke` | Contrast |
+|------|--------|---------|----------|----------|
+| **Information** (primary, entry points) | `#dbeafe` | `#1e3a5f` | `#1e3a5f` | 9.1:1 |
+| **Success** (outputs, completed states) | `#dcfce7` | `#14532d` | `#14532d` | 10.5:1 |
+| **Warning** (external dependencies, caution) | `#fef3c7` | `#4a2c00` | `#b45309` | 8.3:1 |
+| **Error / Alert** (failure states, blockers) | `#fee2e2` | `#7f1d1d` | `#b91c1c` | 8.7:1 |
+| **Documentation** (specs, instructions, AI) | `#f3e8ff` | `#3b0764` | `#7e22ce` | 10.2:1 |
+| **Neutral** (supporting nodes, connectors) | `#f1f5f9` | `#0f172a` | `#334155` | 14.7:1 |
+| **Highlight** (key actions, automation) | `#ecfdf5` | `#064e3b` | `#059669` | 10.8:1 |
+
+**Usage:**
+
+```mermaid
+---
+accTitle: Example colour usage
+accDescr: Shows the correct way to apply the approved colour palette with explicit fill, color, and stroke.
+---
+flowchart LR
+    A[Entry Point] --> B[Automation Step] --> C[Output]
+    style A fill:#dbeafe,color:#1e3a5f,stroke:#1e3a5f
+    style B fill:#ecfdf5,color:#064e3b,stroke:#059669
+    style C fill:#dcfce7,color:#14532d,stroke:#14532d
 ```
+
+**Rules:**
+
+- Only use colours from the approved palette above, or colours you have manually verified using `scripts/validation/validate-mermaid-colour-contrast.js`.
+- Never use `fill:#e1f5fe` without `color:#1e3a5f` (the old single-property pattern fails in dark mode).
+- Never use inline colour strings not from this palette without running the contrast validator first.
+- Do not rely on colour alone to convey meaning — use node shape and label text as the primary communicators.
+
+---
+
+## Theme Initialisation
+
+Include a theme init block only when you have a specific reason. The default theme is correct for nearly all cases:
+
+```text
 %%{init: {'theme': 'default'}}%%
 ```
 
-Standard colors:
+Do **not** use `theme: 'dark'` in diagram definitions — this forces dark mode regardless of the viewer's system preference and creates contrast problems with the approved palette.
+
+For subgraph labels on dark backgrounds, prefer changing the subgraph border and title with inline styles rather than switching the whole theme.
+
+---
+
+## Emoji in Node Labels
+
+Phosphor Icons and other SVG icon sets **cannot** be used in GitHub-rendered Mermaid diagrams. GitHub's embedded renderer does not support the Mermaid v11 `@{ icon: }` syntax.
+
+Use the following canonical emoji vocabulary for node types. Apply consistently across all diagrams in the repository:
+
+| Node type | Emoji | Example label |
+|-----------|-------|---------------|
+| Entry / start | (none — use a rounded node shape) | `([Start])` |
+| User / developer | 👤 | `[👤 Developer]` |
+| Repository / storage | 📁 | `[📁 Repository]` |
+| Workflow / automation | ⚙️ | `[⚙️ Automation]` |
+| Documentation / instructions | 📋 | `[📋 Instructions]` |
+| AI / Copilot | 🤖 | `[🤖 AI Agent]` |
+| Template | 📝 | `[📝 Template]` |
+| Label / tag | 🏷️ | `[🏷️ Labels]` |
+| Security | 🛡️ | `[🛡️ Security]` |
+| Analytics / reporting | 📊 | `[📊 Report]` |
+| Deployment / release | 🚀 | `[🚀 Deploy]` |
+| Success / check | ✅ | `[✅ Passed]` |
+| Error / failure | ❌ | `[❌ Failed]` |
+| Warning | ⚠️ | `[⚠️ Review needed]` |
+| External service | 🌐 | `[🌐 External API]` |
+| Organisation | 🏛️ | `[🏛️ .github Hub]` |
+| Tests | 🧪 | `[🧪 Test Suite]` |
+| Lock / protected | 🔒 | `[🔒 Protected]` |
+
+**Rules:**
+
+- Use at most one emoji per node label.
+- Place the emoji at the start of the label, followed by a space.
+- Never use emoji as the entire label — always include a text description.
+- Do not use emoji in subgraph titles where they are not consistently supported.
+
+---
+
+## Layout and Clarity
+
+- **One concept per diagram.** If a diagram needs more than ~12 nodes, split it.
+- **Direction convention:**
+  - Left-to-right (`LR`) for linear pipelines, data flows, and timelines.
+  - Top-down (`TD`) for hierarchies, trees, and decision flows.
+- **Label length:** Keep node labels to 3–5 words maximum.
+- **Subgraph titles:** Use plain text, no emoji, no special characters.
+- **Arrow labels:** Use sparingly — only when the relationship is not obvious from context.
+- **Avoid crossing arrows** — rearrange node order to keep flows readable.
+
+---
+
+## Validation
+
+Run before every commit:
+
+```bash
+npm run validate:mermaid-syntax        # Validates diagram type, direction, bracket matching
+npm run validate:mermaid-accessibility # Checks for accTitle and accDescr
+npm run validate:mermaid-contrast      # WCAG 2.2 AA colour contrast check (new)
+```
+
+The PR validation workflow (`.github/workflows/validate-mermaid-pr.yml`) runs all three checks automatically on every pull request that modifies `.md` files. A failing contrast check **blocks merge**.
 
-- Primary actions: Blue
-- Warnings: Orange
-- Errors: Red
-- Success: Green
+To validate only changed files locally:
 
-## Testing and Validation
+```bash
+node scripts/validation/validate-mermaid-colour-contrast.js --changed-files=path/to/file.md
+```
+
+---
+
+## Repository-wide Update Process
+
+When diagrams across the repository need to be updated (new palette, new structural requirements):
+
+1. **Open a `chore/` or `docs/` branch** — e.g., `docs/mermaid-colour-standards-v2`.
+2. **Run the fixer script** to apply approved palette colours to all existing style declarations:
+
+   ```bash
+   node scripts/fix-mermaid-diagrams.js
+   ```
 
-- Test in GitHub markdown preview
-- Verify on GitHub Pages (if deployed)
-- Check mobile rendering
-- Provide text alternative for complex diagrams
+3. **Run all three validators** to confirm no regressions:
 
-## Best Practices
+   ```bash
+   npm run validate:mermaid-syntax && npm run validate:mermaid-accessibility && npm run validate:mermaid-contrast
+   ```
 
-- Place caption below diagram with description
-- Link to detailed documentation from diagram
-- Update diagrams when processes change
-- Use consistent naming across diagrams
+4. **Open a PR targeting `develop`** with a description that lists all files changed.
+5. The CI workflow will re-validate on the PR — review any residual findings.
 
 ---
 
-## Related Files
+## Testing and Rendering
 
-- [documentation-formats.instructions.md](./documentation-formats.instructions.md) — Markdown and diagram standards
-- [readme.instructions.md](./readme.instructions.md) — README structure and diagram placement
+- Test all diagrams in the [Mermaid Live Editor](https://mermaid.live/) before committing.
+- Check both GitHub light mode and dark mode rendering in the GitHub preview.
+- Confirm mobile rendering is readable (diagrams should not require horizontal scroll on a 375px viewport).
+- Provide a plain-text alternative directly below any diagram that contains more than 7 nodes or represents a critical process.
 
 ---
+
+## Related Files
+
+- [documentation-formats.instructions.md](./documentation-formats.instructions.md) — Markdown and diagram standards
+- [a11y.instructions.md](./a11y.instructions.md) — WCAG 2.2 AA accessibility standards
+- [scripts/validation/validate-mermaid-colour-contrast.js](../scripts/validation/validate-mermaid-colour-contrast.js) — Colour contrast validator
+- [scripts/validation/validate-mermaid-accessibility.js](../scripts/validation/validate-mermaid-accessibility.js) — accTitle/accDescr validator
+- [scripts/validation/validate-mermaid-syntax.js](../scripts/validation/validate-mermaid-syntax.js) — Syntax validator
+- [.github/workflows/validate-mermaid-pr.yml](../.github/workflows/validate-mermaid-pr.yml) — PR validation workflow
diff --git a/package.json b/package.json
index 20b1042c..c9a31000 100644
--- a/package.json
+++ b/package.json
@@ -105,6 +105,8 @@
     "validate:memory:examples": "node scripts/validation/validate-memory.js --examples-only",
     "validate:mermaid-accessibility": "node scripts/validation/validate-mermaid-accessibility.js",
     "validate:mermaid-syntax": "node scripts/validation/validate-mermaid-syntax.js",
+    "validate:mermaid-contrast": "node scripts/validation/validate-mermaid-colour-contrast.js",
+    "validate:mermaid": "npm run validate:mermaid-syntax && npm run validate:mermaid-accessibility && npm run validate:mermaid-contrast",
     "validate:readme-links": "node scripts/validation/validate-readme-links.js",
     "validate:wceu:phase1": "node scripts/verify-wceu-readiness.js",
     "validate:wceu:phase2": "node scripts/validate-phase2-completion.js",
diff --git a/scripts/validation/validate-mermaid-colour-contrast.js b/scripts/validation/validate-mermaid-colour-contrast.js
new file mode 100644
index 00000000..83a2506f
--- /dev/null
+++ b/scripts/validation/validate-mermaid-colour-contrast.js
@@ -0,0 +1,486 @@
+#!/usr/bin/env node
+/**
+ * Validate WCAG 2.2 AA colour contrast compliance in Mermaid diagrams.
+ *
+ * Checks every `style X fill:#colour` declaration and verifies:
+ * 1. An explicit `color` (text colour) is set alongside each `fill`.
+ * 2. The fill/color pair meets the WCAG AA minimum contrast ratio of 4.5:1.
+ *
+ * Scans all .md files (not just READMEs) to cover instructions, docs, etc.
+ *
+ * @module scripts/validation/validate-mermaid-colour-contrast
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { globSync } from "glob";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.join(__dirname, "../../");
+
+const WCAG_AA_NORMAL_TEXT = 4.5;
+const WCAG_AA_LARGE_TEXT = 3.0;
+
+// Mermaid default text colours per theme (approximations).
+// When no explicit `color` is set, the renderer uses these.
+const MERMAID_THEME_TEXT_DEFAULTS = {
+  default: "#333333",
+  base: "#333333",
+  neutral: "#333333",
+  dark: "#ffffff", // dark mode renders white text — this is the failure case
+  forest: "#333333",
+  "high-contrast": "#000000",
+};
+
+const MD_FILES = globSync("**/*.md", {
+  cwd: ROOT,
+  ignore: [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/coverage/**",
+    "**/logs/**",
+    "**/.github/projects/**",
+  ],
+}).sort();
+
+// ---------------------------------------------------------------------------
+// Colour utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Expand 3-digit hex to 6-digit.
+ * @param {string} hex
+ * @returns {string} 6-digit hex without leading #
+ */
+function normaliseHex(hex) {
+  const h = hex.replace(/^#/, "");
+  if (h.length === 3) {
+    return h
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  return h;
+}
+
+/**
+ * Convert a hex colour to WCAG relative luminance.
+ * @param {string} hex  e.g. "#e1f5fe" or "#fff"
+ * @returns {number}
+ */
+function relativeLuminance(hex) {
+  const h = normaliseHex(hex);
+  const r = parseInt(h.slice(0, 2), 16) / 255;
+  const g = parseInt(h.slice(2, 4), 16) / 255;
+  const b = parseInt(h.slice(4, 6), 16) / 255;
+
+  const linearise = (c) =>
+    c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+
+  return 0.2126 * linearise(r) + 0.7152 * linearise(g) + 0.0722 * linearise(b);
+}
+
+/**
+ * WCAG contrast ratio between two hex colours.
+ * @param {string} hex1
+ * @param {string} hex2
+ * @returns {number}
+ */
+function contrastRatio(hex1, hex2) {
+  const l1 = relativeLuminance(hex1);
+  const l2 = relativeLuminance(hex2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Attempt to resolve a named CSS colour to hex. Covers the subset most likely
+ * to appear in Mermaid style declarations.
+ * @param {string} name
+ * @returns {string|null}
+ */
+function namedColourToHex(name) {
+  const map = {
+    black: "#000000",
+    white: "#ffffff",
+    red: "#ff0000",
+    green: "#008000",
+    blue: "#0000ff",
+    yellow: "#ffff00",
+    orange: "#ffa500",
+    purple: "#800080",
+    pink: "#ffc0cb",
+    gray: "#808080",
+    grey: "#808080",
+    darkgray: "#a9a9a9",
+    darkgrey: "#a9a9a9",
+    lightgray: "#d3d3d3",
+    lightgrey: "#d3d3d3",
+    navy: "#000080",
+    teal: "#008080",
+    aqua: "#00ffff",
+    cyan: "#00ffff",
+    fuchsia: "#ff00ff",
+    magenta: "#ff00ff",
+    silver: "#c0c0c0",
+    maroon: "#800000",
+    olive: "#808000",
+    lime: "#00ff00",
+    transparent: null,
+    none: null,
+  };
+  return map[name.toLowerCase()] ?? null;
+}
+
+/**
+ * Parse a colour string (hex or named) to hex.
+ * Returns null when the colour cannot be resolved (e.g. CSS vars, gradients).
+ * @param {string} colour
+ * @returns {string|null}
+ */
+function parseColour(colour) {
+  if (!colour) return null;
+  const trimmed = colour.trim().toLowerCase();
+  if (/^#[0-9a-f]{3,6}$/.test(trimmed)) return trimmed;
+  return namedColourToHex(trimmed);
+}
+
+// ---------------------------------------------------------------------------
+// Diagram extraction & parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract raw mermaid diagram blocks from markdown content.
+ * @param {string} content
+ * @returns {Array<{raw: string, startLine: number}>}
+ */
+function extractDiagrams(content) {
+  const diagrams = [];
+  const lines = content.split("\n");
+  let inBlock = false;
+  let blockStart = -1;
+  let blockLines = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!inBlock && /^```mermaid\s*$/.test(line.trim())) {
+      inBlock = true;
+      blockStart = i + 1;
+      blockLines = [];
+    } else if (inBlock && /^```\s*$/.test(line.trim())) {
+      diagrams.push({ raw: blockLines.join("\n"), startLine: blockStart });
+      inBlock = false;
+      blockLines = [];
+    } else if (inBlock) {
+      blockLines.push(line);
+    }
+  }
+
+  return diagrams;
+}
+
+/**
+ * Detect the active theme from a diagram's %%{init:...}%% block.
+ * @param {string} diagramRaw
+ * @returns {string}
+ */
+function detectTheme(diagramRaw) {
+  const match = diagramRaw.match(/%%\{.*?'theme'\s*:\s*'([^']+)'/);
+  if (match) return match[1].toLowerCase();
+  const dq = diagramRaw.match(/%%\{.*?"theme"\s*:\s*"([^"]+)"/);
+  if (dq) return dq[1].toLowerCase();
+  return "default";
+}
+
+/**
+ * Parse all style declarations from a diagram.
+ * Handles:
+ *   style NodeId fill:#colour
+ *   style NodeId fill:#colour,color:#colour,stroke:#colour
+ *   style NodeId fill:#colour,color:#colour
+ *
+ * @param {string} diagramRaw
+ * @returns {Array<{nodeId: string, fill: string|null, color: string|null, raw: string, line: number}>}
+ */
+function parseStyleDeclarations(diagramRaw) {
+  const results = [];
+  const lines = diagramRaw.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Match `style <NodeId> <properties>`
+    const styleMatch = line.match(/^\s*style\s+(\S+)\s+(.+)/);
+    if (!styleMatch) continue;
+
+    const nodeId = styleMatch[1];
+    const props = styleMatch[2];
+
+    // Extract fill colour
+    const fillMatch = props.match(/\bfill\s*:\s*([^,;\s]+)/i);
+    const fill = fillMatch ? fillMatch[1].trim() : null;
+
+    // Extract text colour
+    const colorMatch = props.match(/\bcolor\s*:\s*([^,;\s]+)/i);
+    const color = colorMatch ? colorMatch[1].trim() : null;
+
+    results.push({ nodeId, fill, color, raw: line.trim(), line: i });
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Validation logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate contrast for a single style declaration.
+ * @param {{nodeId: string, fill: string|null, color: string|null, raw: string}} styleDecl
+ * @param {string} theme  Detected diagram theme
+ * @returns {Array<{level: 'error'|'warning', message: string}>}
+ */
+function validateStyleContrast(styleDecl, theme) {
+  const issues = [];
+  const { nodeId, fill, color } = styleDecl;
+
+  if (!fill) return issues;
+
+  const fillHex = parseColour(fill);
+  if (!fillHex) {
+    // Cannot validate non-hex / CSS variable fills — skip silently
+    return issues;
+  }
+
+  if (!color) {
+    // No explicit text colour — determine the theme default
+    const defaultTextHex =
+      MERMAID_THEME_TEXT_DEFAULTS[theme] ?? MERMAID_THEME_TEXT_DEFAULTS.default;
+    const ratio = contrastRatio(fillHex, defaultTextHex);
+
+    issues.push({
+      level: "warning",
+      message:
+        `Node "${nodeId}": fill ${fill} has no explicit color. ` +
+        `Against the "${theme}" theme default text (${defaultTextHex}) ` +
+        `the contrast ratio is ${ratio.toFixed(2)}:1 — ` +
+        (ratio >= WCAG_AA_NORMAL_TEXT
+          ? `passes AA for the "${theme}" theme, but will FAIL in dark mode. Add color: explicitly.`
+          : `FAILS WCAG AA (${WCAG_AA_NORMAL_TEXT}:1 required). Add color: explicitly.`),
+    });
+
+    // Also check against dark-mode text (white) for the "missing color" case
+    const darkRatio = contrastRatio(fillHex, "#ffffff");
+    if (darkRatio < WCAG_AA_NORMAL_TEXT) {
+      issues.push({
+        level: "error",
+        message:
+          `Node "${nodeId}": fill ${fill} without explicit color FAILS in dark mode ` +
+          `(white text contrast: ${darkRatio.toFixed(2)}:1, minimum 4.5:1).`,
+      });
+    }
+
+    return issues;
+  }
+
+  const colorHex = parseColour(color);
+  if (!colorHex) return issues;
+
+  const ratio = contrastRatio(fillHex, colorHex);
+  if (ratio < WCAG_AA_NORMAL_TEXT) {
+    issues.push({
+      level: "error",
+      message:
+        `Node "${nodeId}": fill ${fill} / color ${color} contrast ratio is ${ratio.toFixed(2)}:1 — ` +
+        `FAILS WCAG AA 2.2 (${WCAG_AA_NORMAL_TEXT}:1 required for normal text).`,
+    });
+  }
+
+  return issues;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = process.argv.slice(2);
+  const changedFilesArg = args.find((a) => a.startsWith("--changed-files="));
+  const targetFiles = changedFilesArg
+    ? changedFilesArg.replace("--changed-files=", "").split(",").filter(Boolean)
+    : MD_FILES;
+
+  console.log("🎨 Validating Mermaid colour contrast (WCAG 2.2 AA)...\n");
+  console.log(`Scanning ${targetFiles.length} file(s)\n`);
+
+  const report = {
+    filesScanned: 0,
+    diagramsScanned: 0,
+    stylesChecked: 0,
+    errors: 0,
+    warnings: 0,
+    findings: [],
+  };
+
+  for (const relPath of targetFiles) {
+    const filePath = path.isAbsolute(relPath)
+      ? relPath
+      : path.join(ROOT, relPath);
+
+    if (!fs.existsSync(filePath)) continue;
+    const content = fs.readFileSync(filePath, "utf-8");
+    const diagrams = extractDiagrams(content);
+    if (diagrams.length === 0) continue;
+
+    report.filesScanned++;
+    let fileHasIssues = false;
+
+    for (let di = 0; di < diagrams.length; di++) {
+      const diagram = diagrams[di];
+      report.diagramsScanned++;
+
+      const theme = detectTheme(diagram.raw);
+      const styles = parseStyleDeclarations(diagram.raw);
+
+      for (const style of styles) {
+        report.stylesChecked++;
+        const issues = validateStyleContrast(style, theme);
+
+        for (const issue of issues) {
+          if (issue.level === "error") report.errors++;
+          else report.warnings++;
+
+          report.findings.push({
+            file: relPath,
+            diagramIndex: di + 1,
+            theme,
+            level: issue.level,
+            message: issue.message,
+            rawStyle: style.raw,
+          });
+
+          if (!fileHasIssues) {
+            console.log(`\n📄 ${relPath}`);
+            fileHasIssues = true;
+          }
+
+          const icon = issue.level === "error" ? "❌" : "⚠️ ";
+          console.log(`   ${icon} Diagram ${di + 1}: ${issue.message}`);
+        }
+      }
+    }
+
+    if (!fileHasIssues && diagrams.length > 0) {
+      console.log(
+        `✅ ${relPath} — ${diagrams.length} diagram(s), all styles pass`,
+      );
+    }
+  }
+
+  console.log("\n" + "=".repeat(70));
+  console.log("🎨 COLOUR CONTRAST SUMMARY");
+  console.log("=".repeat(70));
+  console.log(`Files scanned:    ${report.filesScanned}`);
+  console.log(`Diagrams scanned: ${report.diagramsScanned}`);
+  console.log(`Styles checked:   ${report.stylesChecked}`);
+  console.log(`Errors:           ${report.errors}`);
+  console.log(`Warnings:         ${report.warnings}`);
+
+  if (report.findings.length > 0) {
+    console.log("\n📋 FINDINGS:");
+    for (const f of report.findings) {
+      console.log(
+        `\n  ${f.level.toUpperCase()} in ${f.file} (Diagram #${f.diagramIndex}, theme: ${f.theme})`,
+      );
+      console.log(`  Style: ${f.rawStyle}`);
+      console.log(`  Issue: ${f.message}`);
+    }
+  }
+
+  if (report.errors > 0) {
+    console.log(
+      `\n❌ ${report.errors} contrast error(s) found. See approved palette in instructions/mermaid.instructions.md`,
+    );
+  } else if (report.warnings > 0) {
+    console.log(
+      `\n⚠️  ${report.warnings} warning(s). Add explicit color: to every fill: declaration to guarantee contrast in all themes.`,
+    );
+  } else {
+    console.log(
+      "\n✅ All style declarations meet WCAG 2.2 AA contrast requirements.",
+    );
+  }
+
+  // Write report
+  const reportDir = path.join(ROOT, ".github/reports/mermaid");
+  fs.mkdirSync(reportDir, { recursive: true });
+  const today = new Date().toISOString().slice(0, 10);
+  const reportPath = path.join(reportDir, `colour-contrast-report-${today}.md`);
+
+  const reportMd = `---
+title: Mermaid Colour Contrast Report
+description: WCAG 2.2 AA colour contrast validation for all Mermaid diagrams
+file_type: documentation
+created_date: "${today}"
+last_updated: "${today}"
+tags: ["mermaid", "a11y", "wcag", "colour-contrast"]
+status: active
+stability: stable
+---
+
+# Mermaid Colour Contrast Report
+
+**Generated**: ${new Date().toISOString()}
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Files scanned | ${report.filesScanned} |
+| Diagrams scanned | ${report.diagramsScanned} |
+| Style declarations checked | ${report.stylesChecked} |
+| Errors (contrast failures) | ${report.errors} |
+| Warnings (missing explicit color) | ${report.warnings} |
+
+## Findings
+
+${
+  report.findings.length === 0
+    ? "✅ All style declarations meet WCAG 2.2 AA requirements."
+    : report.findings
+        .map(
+          (f) =>
+            `### ${f.level.toUpperCase()}: \`${f.file}\` — Diagram #${f.diagramIndex}\n\n` +
+            `- **Theme**: ${f.theme}\n` +
+            `- **Style**: \`${f.rawStyle}\`\n` +
+            `- **Issue**: ${f.message}\n`,
+        )
+        .join("\n")
+}
+
+## Approved Colour Palette
+
+See \`instructions/mermaid.instructions.md\` for the full approved palette with pre-verified WCAG AA contrast pairs.
+
+| Role | fill | color | stroke | Contrast |
+|------|------|-------|--------|----------|
+| Information | \`#dbeafe\` | \`#1e3a5f\` | \`#1e3a5f\` | 9.1:1 |
+| Success | \`#dcfce7\` | \`#14532d\` | \`#14532d\` | 10.5:1 |
+| Warning | \`#fef3c7\` | \`#4a2c00\` | \`#b45309\` | 8.3:1 |
+| Error / Alert | \`#fee2e2\` | \`#7f1d1d\` | \`#b91c1c\` | 8.7:1 |
+| Documentation | \`#f3e8ff\` | \`#3b0764\` | \`#7e22ce\` | 10.2:1 |
+| Neutral | \`#f1f5f9\` | \`#0f172a\` | \`#334155\` | 14.7:1 |
+| Highlight | \`#ecfdf5\` | \`#064e3b\` | \`#059669\` | 10.8:1 |
+`;
+
+  fs.writeFileSync(reportPath, reportMd);
+  console.log(`\n📄 Report saved to ${path.relative(ROOT, reportPath)}`);
+
+  process.exit(report.errors > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error("Colour contrast validation error:", err);
+  process.exit(1);
+});