[codex] Mermaid diagrams WCAG 2.2 AA contrast sweep#987
Conversation
|
✅ Template check passed after update. Thanks for fixing the PR description. |
|
Warning Review limit reached
More reviews will be available in 41 minutes and 54 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (30)
📝 WalkthroughWalkthroughA repository-wide Mermaid WCAG 2.2 AA compliance pass: introduces a new colour-contrast validator script, expands all three Mermaid validation scripts to cover all ChangesMermaid WCAG 2.2 AA Accessibility & Contrast Sweep
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Metadata governance
|
There was a problem hiding this comment.
Code Review
This pull request introduces WCAG 2.2 AA colour contrast validation for Mermaid diagrams across the repository. Key changes include adding a new colour contrast validation script, updating the automatic diagram fixer to apply the approved palette, and expanding the accessibility and syntax validators to scan all markdown files instead of just READMEs. The review feedback highlights two important improvements for the contrast validation script: stripping Mermaid comments before parsing style declarations to prevent false positives, and verifying that paths passed to the script are files rather than directories to avoid potential crashes.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| for (let i = 0; i < lines.length; i++) { | ||
| const line = lines[i]; | ||
| const match = line.match(/^\s*(style|classDef)\s+(\S+)\s+(.+)/); | ||
| if (!match) continue; |
There was a problem hiding this comment.
Mermaid style and classDef declarations can contain comments starting with %%. If a comment contains keywords like fill: or color:, it can interfere with the regex matching and cause false positives or incorrect parsing. Stripping comments before parsing ensures only active style properties are validated.
| for (let i = 0; i < lines.length; i++) { | |
| const line = lines[i]; | |
| const match = line.match(/^\s*(style|classDef)\s+(\S+)\s+(.+)/); | |
| if (!match) continue; | |
| for (let i = 0; i < lines.length; i++) { | |
| const line = lines[i]; | |
| const cleanLine = line.split("%%")[0]; | |
| const match = cleanLine.match(/^\\s*(style|classDef)\\s+(\\S+)\\s+(.+)/); | |
| if (!match) continue; |
| ? relPath | ||
| : path.join(ROOT, relPath); | ||
|
|
||
| if (!fs.existsSync(filePath)) continue; |
There was a problem hiding this comment.
If a directory path is passed to --changed-files=, fs.existsSync will return true, but fs.readFileSync will throw an EISDIR error and crash the script. Adding a check to ensure the path is a file prevents potential crashes.
| if (!fs.existsSync(filePath)) continue; | |
| if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) continue; |
5b582f6 to
66dce1f
Compare
🎨 Mermaid Diagram Validation✅ All Mermaid diagram checks passed.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5b582f6c7f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # This is a placeholder for actual validation logic | ||
| } | ||
| done | ||
| run: npm run validate:mermaid-syntax |
There was a problem hiding this comment.
This now invokes the Node validator, but this job (and the parallel accessibility/contrast jobs) only runs setup-node with npm caching; it never installs the repo dependencies. On a fresh runner the scripts import glob from devDependencies, while the setup-node cache does not provide node_modules (setup-node docs), so dispatching scope: syntax, accessibility, contrast, or all fails before any Mermaid checks run. Add npm ci in each validation job or run these checks in the existing audit job after its install.
Useful? React with 👍 / 👎.
| const ROOT = path.join(__dirname, "../../"); | ||
|
|
||
| const README_FILES = globSync("**/README.md", { | ||
| const MARKDOWN_FILES = globSync("**/*.{md,mdx}", { |
There was a problem hiding this comment.
This new repository-wide glob omits dot: true, so glob skips Markdown under hidden directories. That leaves the Mermaid syntax job checking 45 diagrams while the new accessibility/contrast validators check 60, missing .github/README.md, .github/ISSUE_TEMPLATE/README.md, .vscode/README.md, and report diagrams; syntax errors in those hidden docs will still pass validate:mermaid-syntax. Add dot: true here as the other Mermaid validators do.
Useful? React with 👍 / 👎.
| - name: Run Mermaid diagram fixes | ||
| if: ${{ env.UPDATE_SCOPE == 'all' || env.UPDATE_SCOPE == 'mermaid' }} | ||
| run: node .github/scripts/fix-mermaid-diagrams.js | ||
| run: node scripts/fix-mermaid-diagrams.js |
There was a problem hiding this comment.
With this workflow now calling scripts/fix-mermaid-diagrams.js, the step reaches a file under the root package, which declares "type": "module"; that file still starts with CommonJS require, so node scripts/fix-mermaid-diagrams.js throws ReferenceError: require is not defined before making any Mermaid fixes. Because this step is continue-on-error, the workflow can proceed and report success without applying the intended accessibility/colour updates.
Useful? React with 👍 / 👎.
7780972 to
a76b620
Compare
a76b620 to
52fbc6a
Compare
There was a problem hiding this comment.
Actionable comments posted: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
.github/workflows/readme-audit.yml (2)
91-101:⚠️ Potential issue | 🟠 Major | ⚡ Quick winValidator jobs run before dependencies are installed.
These jobs execute
npm run validate:*, but there is nonpm cistep in the shown job setup. That can fail immediately on module imports (for exampleglob).Suggested patch
- name: Set up Node.js uses: actions/setup-node@v4 with: node-version: "18" cache: "npm" + - name: Install dependencies + run: npm ciAlso applies to: 118-120, 136-137
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-audit.yml around lines 91 - 101, The readme-audit.yml workflow is missing a dependency installation step before running validation commands. Add an `npm ci` step between the "Set up Node.js" step and the "Validate Mermaid diagrams" step (and apply the same fix to the other affected validation jobs mentioned at lines 118-120 and 136-137). This ensures that npm dependencies like glob are installed before any npm run validate commands are executed, preventing immediate module import failures during validation.
82-138:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd explicit least-privilege
permissionsfor these jobs.Nice workflow expansion overall — now let’s lock token scope down explicitly (read-only by default, elevate only where truly needed).
Suggested patch
validate-syntax: name: Validate Mermaid Syntax runs-on: ubuntu-latest + permissions: + contents: read @@ check-accessibility: name: Check WCAG Compliance runs-on: ubuntu-latest + permissions: + contents: read @@ check-contrast: name: Check Mermaid Colour Contrast runs-on: ubuntu-latest + permissions: + contents: readAs per coding guidelines, GitHub Actions workflows should use least-privilege permissions and default to read-only.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-audit.yml around lines 82 - 138, The three jobs validate-syntax, check-accessibility, and check-contrast are missing explicit least-privilege permissions blocks. Add a permissions section to each job setting contents to read, since these jobs only perform read operations on the repository (checking out code and running validation scripts without modifying anything). This follows the principle of defaulting to read-only access and only elevating permissions where truly needed.Sources: Coding guidelines, Linters/SAST tools
scripts/fix-mermaid-diagrams.js (1)
142-159:⚠️ Potential issue | 🟠 Major | ⚡ Quick winBroaden metadata detection to avoid duplicate
accTitle/accDescrentriesQuick gremlin on Line 142 and Line 157: the fixer only detects
accTitle:/accDescr:. Valid forms likeaccTitle My titleandaccDescr { ... }are treated as missing, so duplicate accessibility fields can be injected.Suggested patch
- if (!nextDiagram.includes("accTitle:")) { + const hasAccTitle = + /(?:^|\n)\s*accTitle(?:\s*[:=]|\s+)/m.test(nextDiagram); + if (!hasAccTitle) { const firstLine = nextDiagram.split("\n")[0]; @@ - if (!nextDiagram.includes("accDescr:")) { + const hasAccDescr = + /(?:^|\n)\s*accDescr(?:\s*[:=]|\s*{|\s+)/m.test(nextDiagram); + if (!hasAccDescr) { nextDiagram = `${nextDiagram}\naccDescr: Detailed diagram`; modified = true; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/fix-mermaid-diagrams.js` around lines 142 - 159, The accessibility metadata detection is too narrow - the includes() checks for "accTitle:" and "accDescr:" on lines 142 and 157 only match one specific format, but mermaid allows alternative formats like "accTitle My title" (without colon) and "accDescr { ... }" (with braces). Broaden both detection checks to match any occurrence of the metadata field name itself rather than just the colon-suffixed variants, so that existing accessibility metadata in alternative formats is properly detected and duplicate entries are not injected. Consider using regex or multiple include checks to catch all valid variations of these fields.
🧹 Nitpick comments (1)
.github/workflows/readme-audit.yml (1)
88-90: ⚡ Quick winHarden checkout steps by disabling credential persistence.
For pure validation jobs, set
persist-credentials: falseonactions/checkoutto reduce accidental token exposure paths.Suggested patch
- name: Checkout repository uses: actions/checkout@v4 + with: + persist-credentials: falseAs per coding guidelines, workflow security checks should include safe secret handling and minimised credential exposure.
Also applies to: 109-111, 127-129
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-audit.yml around lines 88 - 90, The actions/checkout@v4 steps in the readme-audit workflow do not disable credential persistence, increasing the risk of accidental token exposure. Add the `persist-credentials: false` configuration parameter to all three instances of the actions/checkout@v4 step (the one at the specified location and the two additional instances noted in the comment) to minimize credential exposure during the validation job execution, as per security guidelines for pure validation workflows.Sources: Coding guidelines, Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/reports/mermaid-accessibility-report.md:
- Line 3: Update the description text in the accessibility report to reflect the
current number of diagrams being audited. Change "all 24 Mermaid diagrams" to
"all 60 Mermaid diagrams" in the description field to ensure consistency between
the documentation and the actual audit scope. This simple numeric update will
prevent confusion about the audit coverage.
- Line 35: In the mermaid-accessibility-report.md file, locate the heading "##
Files Analyzed" and change the spelling from "Analyzed" (US English) to
"Analysed" (UK English) to comply with the repository's documentation standards
that require UK English spelling throughout all markdown and text files.
In @.github/reports/mermaid-validation-report.md:
- Line 3: Update the description field in the frontmatter at line 3 of the
mermaid-validation-report.md file. The current description states the validation
results are "for repository README files" but the report scope has expanded to
cover all Markdown and MDX files across the repository. Replace the
README-specific wording with text that accurately reflects the repo-wide scope
of the validation audit.
- Line 24: In the mermaid-validation-report.md file, change the section heading
"## Files Analyzed" to "## Files Analysed" to comply with UK English spelling
standards as required by the project's coding guidelines for markdown files.
This ensures consistency with other UK English terms used throughout the
documentation.
In @.github/workflows/readme-update.yml:
- Around line 70-74: The "Validate Mermaid colour contrast" step currently has
continue-on-error set to true, which allows the workflow to pass even when the
npm run validate:mermaid-contrast command fails. Remove the continue-on-error:
true line from this step to make the contrast validation blocking, ensuring that
non-compliant Mermaid diagrams will cause the workflow to fail and prevent the
commit from proceeding.
In `@instructions/mermaid.instructions.md`:
- Line 16: The instructions at line 16 claim that the validation workflow
"enforces the accessibility and syntax rules automatically," but this is
inaccurate. The provided validator and fixer snippets only enforce the presence
of `accTitle` and `accDescr` attributes without enforcing their proper placement
within the `---` header wrapper block format or preventing duplicate inline
declarations. Revise the claim on line 16 to accurately reflect what is actually
enforced by the current tooling, or update the validator/fixer snippets to fully
enforce header-block placement and duplicate-inline constraints. The same
accuracy issue applies to the rules mentioned around lines 68-71, so update
those as well to match the actual enforcement behavior.
- Around line 38-47: The outer fenced code blocks use triple backticks which can
conflict with the inner mermaid code blocks that also use triple backticks,
causing the outer block to terminate prematurely in Markdown renderers. Change
all outer fences from triple backticks (```text) to four backticks (````text) to
properly contain the inner mermaid blocks with their triple backticks. Apply
this change to all occurrences where mermaid examples are nested within text
fences throughout the document, including multiple instances.
- Around line 14-224: The mermaid.instructions.md file does not follow the
required instruction file template structure. Restructure the file to follow the
mandated pattern: start with a Role section, then add Overview, General Rules,
Detailed Guidance, Examples, Validation, and References/Cross-References
sections. Consolidate existing content like "When to Include a Diagram",
"Required Structure", "Diagram Types", "Colour Palette", "Theme Initialisation",
"Emoji in Node Labels", and "Layout and Clarity" into the appropriate sections
(most should fall under General Rules and Detailed Guidance). Ensure the
Validation section includes the npm commands already present. Add a new
References/Cross-References section at the end to link to related documentation
or files.
- Around line 4-11: The frontmatter in the mermaid.instructions.md file is
missing three canonical metadata keys required for all instructions/** files.
Add the missing keys file_type, domain, and stability to the frontmatter
section. The file_type should indicate this is an instruction file, domain
should categorize the subject area (likely "documentation" or "diagrams"), and
stability should indicate the maturity level of the instruction. Ensure all keys
in the canonical pattern (file_type, version, last_updated, owners, tags,
status, domain, stability) are present in the frontmatter block.
In `@scripts/validation/validate-mermaid-colour-contrast.js`:
- Around line 154-161: The validator currently extracts and stores only `fill`
and `color` properties but does not parse or validate the `stroke` property,
which is required as part of the documented fill+color+stroke triple. Extend the
regex matching logic in the section where fillMatch and colorMatch are defined
to also extract the stroke value using a similar pattern. Then update the
validation logic (referenced in the "Also applies to" range at lines 170-225) to
enforce that all three properties (fill, color, and stroke) must be present
together before marking a node as valid, rather than allowing partial matches to
pass validation.
- Around line 176-177: When parseColour(fill) or parseColour(color) returns a
falsy value (indicating an invalid or unsupported color), instead of silently
returning with no issues reported, add an issue entry to the issues array
describing that the color value is invalid or unsupported. This fix should be
applied in two places: when fillHex is falsy after calling parseColour(fill),
and when colorHex is falsy after calling parseColour(color) around the code
region mentioned as also applying to lines 212-214. Each case should push a
descriptive issue object to the issues array before returning it, rather than
returning early with no warnings about the unparseable color values.
---
Outside diff comments:
In @.github/workflows/readme-audit.yml:
- Around line 91-101: The readme-audit.yml workflow is missing a dependency
installation step before running validation commands. Add an `npm ci` step
between the "Set up Node.js" step and the "Validate Mermaid diagrams" step (and
apply the same fix to the other affected validation jobs mentioned at lines
118-120 and 136-137). This ensures that npm dependencies like glob are installed
before any npm run validate commands are executed, preventing immediate module
import failures during validation.
- Around line 82-138: The three jobs validate-syntax, check-accessibility, and
check-contrast are missing explicit least-privilege permissions blocks. Add a
permissions section to each job setting contents to read, since these jobs only
perform read operations on the repository (checking out code and running
validation scripts without modifying anything). This follows the principle of
defaulting to read-only access and only elevating permissions where truly
needed.
In `@scripts/fix-mermaid-diagrams.js`:
- Around line 142-159: The accessibility metadata detection is too narrow - the
includes() checks for "accTitle:" and "accDescr:" on lines 142 and 157 only
match one specific format, but mermaid allows alternative formats like "accTitle
My title" (without colon) and "accDescr { ... }" (with braces). Broaden both
detection checks to match any occurrence of the metadata field name itself
rather than just the colon-suffixed variants, so that existing accessibility
metadata in alternative formats is properly detected and duplicate entries are
not injected. Consider using regex or multiple include checks to catch all valid
variations of these fields.
---
Nitpick comments:
In @.github/workflows/readme-audit.yml:
- Around line 88-90: The actions/checkout@v4 steps in the readme-audit workflow
do not disable credential persistence, increasing the risk of accidental token
exposure. Add the `persist-credentials: false` configuration parameter to all
three instances of the actions/checkout@v4 step (the one at the specified
location and the two additional instances noted in the comment) to minimize
credential exposure during the validation job execution, as per security
guidelines for pure validation workflows.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: e58fccc6-6e29-426e-970e-235adb63d73e
⛔ Files ignored due to path filters (1)
.github/reports/mermaid-diagram-accessibility-spreadsheet.csvis excluded by!**/*.csv
📒 Files selected for processing (29)
.github/ISSUE_TEMPLATE/README.md.github/README.md.github/instructions/.archive/frontmatter.instructions.md.github/instructions/.archive/tests.instructions.md.github/prompts/update-mermaid-diagrams.prompt.md.github/reports/mermaid-accessibility-report.md.github/reports/mermaid-validation-report.md.github/reports/mermaid/colour-contrast-report-2026-06-18.md.github/reports/mermaid/diagram-validation-2025-12-11.md.github/workflows/readme-audit.yml.github/workflows/readme-update.yml.vscode/README.mdCONTRIBUTING.mdREADME.mddocs/AGENT_CREATION.mddocs/HUSKY_PRECOMMITS.mdinstructions/automation.instructions.mdinstructions/documentation-formats.instructions.mdinstructions/linting.instructions.mdinstructions/mermaid.instructions.mdinstructions/quality-assurance.instructions.mdpackage.jsonprofile/README.mdscripts/README.mdscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-colour-contrast.jsscripts/validation/validate-mermaid-syntax.jstests/README.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (18)
**/*.{md,markdown,txt,instructions.md}
📄 CodeRabbit inference engine (CLAUDE.md)
Language: Use UK English throughout (optimise, organisation, colour, behaviour).
Files:
instructions/linting.instructions.mdtests/README.mdCONTRIBUTING.mdscripts/README.mdinstructions/quality-assurance.instructions.mdprofile/README.mdinstructions/automation.instructions.mdREADME.mddocs/HUSKY_PRECOMMITS.mddocs/AGENT_CREATION.mdinstructions/documentation-formats.instructions.mdinstructions/mermaid.instructions.md
**/*.instructions.md
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.instructions.md: Do not create instruction files with a 'references' frontmatter field; use inline links or footer sections instead.
Instruction files must follow the pattern: frontmatter + role declaration + Overview + General Rules + Detailed Guidance + Examples + Validation + References.
Files:
instructions/linting.instructions.mdinstructions/quality-assurance.instructions.mdinstructions/automation.instructions.mdinstructions/documentation-formats.instructions.mdinstructions/mermaid.instructions.md
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
All documentation must follow Markdown formatting standards and include YAML frontmatter as specified in instructions/documentation-formats.instructions.md
Files:
instructions/linting.instructions.mdtests/README.mdCONTRIBUTING.mdscripts/README.mdinstructions/quality-assurance.instructions.mdprofile/README.mdinstructions/automation.instructions.mdREADME.mddocs/HUSKY_PRECOMMITS.mddocs/AGENT_CREATION.mdinstructions/documentation-formats.instructions.mdinstructions/mermaid.instructions.md
instructions/**
⚙️ CodeRabbit configuration file
instructions/**: Review portable instruction files:
- Verify frontmatter follows the canonical pattern (file_type, version, last_updated, owners, tags, status, domain, stability).
- Flag any
references:frontmatter field — prohibited by CLAUDE.md.- Confirm the file has: Overview, General Rules, Detailed Guidance, Examples, Validation, and Cross-References sections.
- Check that language is UK English throughout.
Files:
instructions/linting.instructions.mdinstructions/quality-assurance.instructions.mdinstructions/automation.instructions.mdinstructions/documentation-formats.instructions.mdinstructions/mermaid.instructions.md
**/tests/*.*
⚙️ CodeRabbit configuration file
**/tests/*.*: Review all test files:
- All test files must have a header (purpose, author, date, related files).
- Use clear, descriptive test names and logical structure.
- Include both positive and negative test cases.
- Be discoverable from the main agent/test index.
- Pass all style checks and linting.
Files:
tests/README.md
**/*.{php,js,ts,jsx,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{php,js,ts,jsx,tsx}: Follow WordPress Coding Standards for PHP files, ESLint/Prettier for JS/TS files, and PHPCS/WPCS for PHP files.
Security: Validate all input, escape all output, use nonces, never commit secrets.
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.jsscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-colour-contrast.js
**/*.{js,ts,jsx,tsx,html}
📄 CodeRabbit inference engine (CLAUDE.md)
Performance: Avoid unnecessary JS, defer/lazy-load where possible, prefer native blocks.
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.jsscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-colour-contrast.js
**/*.{php,js,ts}
📄 CodeRabbit inference engine (CLAUDE.md)
Do not enqueue editor-only WordPress assets on the front end (and vice versa).
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.jsscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-colour-contrast.js
**/*.{php,js,css,html}
📄 CodeRabbit inference engine (AGENTS.md)
Follow WordPress Coding Standards (CSS, HTML, JavaScript, PHP) and inline-documentation standards at all times
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.jsscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-colour-contrast.js
**/*.{js,ts,jsx,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
JavaScript and TypeScript files must follow linting standards defined in instructions/languages.instructions.md, including JSDoc documentation
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.jsscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-colour-contrast.js
**/*.{js,ts}
⚙️ CodeRabbit configuration file
**/*.{js,ts}: Review JavaScript/TypeScript:
- Ensure code is linted and follows project style guides.
- Check for dead code, unused variables, and clear function naming.
- Validate accessibility and performance optimisations.
- Ensure tests are isolated and do not depend on external state.
- Check for descriptive test names and clear test structure.
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.jsscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-colour-contrast.js
**/.github/workflows/*.yml
⚙️ CodeRabbit configuration file
**/.github/workflows/*.yml: Review GitHub Actions workflows for this governance repo:
- Security: check for least-privilege permissions (use
permissions:at job level, default to read-only).- Secret handling: ensure secrets are passed via env vars, not interpolated directly into run: steps to prevent injection.
- Action pinning: prefer SHA-pinned actions over mutable tags (e.g.
actions/checkout@v4is acceptable; SHA pins are better).- No
pull_request_targetwith untrusted code execution unless explicitly justified.- Avoid storing sensitive outputs as unmasked step outputs.
- Check for reusable workflow patterns and matrix strategies where appropriate.
- Validate
on:triggers: ensure branch/path filters are present to avoid unnecessary runs.- Confirm workflows are documented, DRY, and maintainable.
- Ensure agent-triggered workflows use
workflow_dispatchwith defined inputs.
Files:
.github/workflows/readme-update.yml.github/workflows/readme-audit.yml
**/docs/**/*.md
⚙️ CodeRabbit configuration file
**/docs/**/*.md: Review documentation files:
- Ensure markdown is linted and formatted per project style guides.
- Flag illogical folder structures, file naming, or misplaced content.
- Confirm documentation is up to date, accurate, and cross-referenced.
- Ensure accessibility (heading hierarchy, alt text for images, UK English).
Files:
docs/HUSKY_PRECOMMITS.mddocs/AGENT_CREATION.md
.github/prompts/**
⚙️ CodeRabbit configuration file
.github/prompts/**: Prefer concise, actionable reviews. Respect documented style precedence. Link suggested fixes.
Files:
.github/prompts/update-mermaid-diagrams.prompt.md
**/.github/prompts/*.md
⚙️ CodeRabbit configuration file
**/.github/prompts/*.md: Review all prompt files:
- Check for clear instructions, examples, and checklist sections.
- Ensure each file has correct YAML frontmatter.
- Confirm the file is referenced in the prompts index.
- Validate structure, naming, and documentation.
Files:
.github/prompts/update-mermaid-diagrams.prompt.md
**/.github/ISSUE_TEMPLATE/*.md
⚙️ CodeRabbit configuration file
**/.github/ISSUE_TEMPLATE/*.md: Review issue template files:
- Ensure valid markdown syntax, logical structure, and clear instructions.
- Validate YAML frontmatter for required fields (title, description, labels).
- Check for accessibility (clear headings, no ambiguous language).
- Confirm templates reference related documentation.
Files:
.github/ISSUE_TEMPLATE/README.md
**/*.{json,yaml,yml}
📄 CodeRabbit inference engine (AGENTS.md)
JSON and YAML files must follow formatting and validation standards defined in instructions/languages.instructions.md
Files:
package.json
**/package.json
⚙️ CodeRabbit configuration file
**/package.json: Review package.json:
- Check for security vulnerabilities and outdated packages.
- Ensure scripts are documented with clear, descriptive names.
- Validate semantic versioning and proper version pinning.
- Confirm devDependencies vs dependencies separation.
- Ensure scripts follow org standards (lint, test, build, format).
Files:
package.json
🪛 LanguageTool
.github/prompts/update-mermaid-diagrams.prompt.md
[uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”.
Context: ... colour contrast checks - Workflow: .github/workflows/readme-audit.yml and `.githu...
(GITHUB)
[uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”.
Context: ....github/workflows/readme-audit.ymland.github/workflows/readme-update.yml` - audit an...
(GITHUB)
[style] ~83-~83: Would you like to use the Oxford spelling “Organization”? The spelling ‘Organisation’ is also correct.
Context: ... ❌ Failed,
(OXFORD_SPELLING_Z_NOT_S)
[formatting] ~111-~111: Consider inserting a comma after ‘yet’ to make the sentence clearer.
Context: ...`` 4. If a documentation file does not yet contain a diagram, only add one when th...
(IF_CLAUSE_COMMA)
instructions/mermaid.instructions.md
[misspelling] ~24-~24: This word is normally spelled as one.
Context: ... when the documentation describes: - A multi-step process or workflow - Component relatio...
(EN_COMPOUNDS_MULTI_STEP)
[uncategorized] ~30-~30: Possible missing comma found.
Context: ...dule Do not force a diagram into a file where a simple list or paragraph is cle...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~132-~132: Would you like to use the Oxford spelling “Initialization”? The spelling ‘Initialisation’ is also correct.
Context: ...alone to convey meaning. --- ## Theme Initialisation Use a theme init block only when there...
(OXFORD_SPELLING_Z_NOT_S)
[style] ~166-~166: Would you like to use the Oxford spelling “Organization”? The spelling ‘Organisation’ is also correct.
Context: ... service | 🌐 | [🌐 External API] | | Organisation | 🏛️ | [🏛️ .github Hub] | | Tests |...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~166-~166: The official name of this software platform is spelled with a capital “H”.
Context: ...External API]| | Organisation | 🏛️ |[🏛️ .github Hub]| | Tests | 🧪 |[🧪 Test Suite]...
(GITHUB)
[uncategorized] ~230-~230: The official name of this software platform is spelled with a capital “H”.
Context: ...ast.js) - Colour contrast validator - [.github/workflows/readme-audit.yml](../.github/...
(GITHUB)
[uncategorized] ~230-~230: The official name of this software platform is spelled with a capital “H”.
Context: ...or - .github/workflows/readme-audit.yml - Audit wor...
(GITHUB)
[uncategorized] ~231-~231: The official name of this software platform is spelled with a capital “H”.
Context: .../readme-audit.yml) - Audit workflow - [.github/workflows/readme-update.yml](../.github...
(GITHUB)
[uncategorized] ~231-~231: The official name of this software platform is spelled with a capital “H”.
Context: ...w - .github/workflows/readme-update.yml - Update w...
(GITHUB)
🪛 zizmor (1.25.2)
.github/workflows/readme-audit.yml
[warning] 82-101: overly broad permissions (excessive-permissions): default permissions used due to no permissions: block
(excessive-permissions)
[warning] 127-128: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
[warning] 121-137: overly broad permissions (excessive-permissions): default permissions used due to no permissions: block
(excessive-permissions)
[error] 128-128: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)
(unpinned-uses)
[error] 131-131: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)
(unpinned-uses)
🔇 Additional comments (25)
instructions/documentation-formats.instructions.md (2)
502-518: 💤 Low valueMinor wording refinement: "Colour" already used in guidance text.
Line 502 correctly uses UK English "colours" in the prose. The colour values in the classDef declarations (lines 513–514) appear to follow the approved palette pattern (e.g.,
fill:#dcfce7,color:#14532d,stroke:#14532d`` for success). This aligns with the WCAG 2.2 AA approved palette referenced in the PR objectives.
404-405: LGTM!Also applies to: 419-420, 433-434, 455-456, 476-477, 547-548
instructions/automation.instructions.md (1)
81-82: LGTM!Also applies to: 669-670
instructions/linting.instructions.md (1)
105-106: LGTM!Also applies to: 141-142
instructions/quality-assurance.instructions.md (1)
80-96: LGTM!Also applies to: 377-378
CONTRIBUTING.md (1)
33-34: LGTM!docs/AGENT_CREATION.md (1)
111-112: LGTM!Also applies to: 149-151, 185-186, 218-219, 308-309, 353-354, 405-406, 478-479, 528-529
docs/HUSKY_PRECOMMITS.md (1)
119-120: LGTM!.github/instructions/.archive/frontmatter.instructions.md (1)
86-87: LGTM!.github/instructions/.archive/tests.instructions.md (1)
87-94: LGTM!Also applies to: 99-115, 180-195
.github/reports/mermaid/diagram-validation-2025-12-11.md (1)
282-290: LGTM!README.md (2)
127-217: 💤 Low valueAcclamation to the colour palette update! 🎨
The repository architecture diagram receives all the accessibility love—
accTitleandaccDescrproperly positioned, and the approved WCAG 2.2 AA colour palette applied consistently. The diagram legibility remains excellent across all node types.One tiny finesse: lines 228-229 and 351-352 show slightly different
accDescrformatting styles (inline vs. block). Whilst both render correctly, standardising to a single format (inline, as most diagrams use) would improve consistency across the entire file. Not blocking, but worth a future polish pass!Source: Coding guidelines
170-180: LGTM!Also applies to: 250-254, 296-300, 411-414
.github/README.md (1)
64-123: 💤 Low valueBrilliant accessibility enhancements across the .github hub documentation! 🌟
All three diagrams now sport proper
accTitleandaccDescrmetadata, and the WCAG 2.2 AA colour palette is applied with consistent contrast ratios. The diagrams remain visually engaging whilst remaining accessible to all users.One stylistic note: You'll notice some diagrams use inline
accDescr: "..."format (lines 216, 266) whilst others use the block formataccDescr { ... }(lines 71-73). Both are valid Mermaid syntax, but standardising to one format across all files in the PR would improve consistency. The inline format is more compact; the block format is clearer for longer descriptions. Current state isn't a blocker, but worth a polish pass across the repository-wide changes.Also applies to: 215-235, 265-323, 406-461
.github/ISSUE_TEMPLATE/README.md (1)
48-79: LGTM!profile/README.md (2)
34-71: LGTM!Also applies to: 95-129, 148-202, 225-244
301-308: ⚡ Quick winSpot of duplication in the footer! 🎯
The lovely "Made with 💚 by LightSpeedWP" footer message appears three times consecutively (lines 301–308). This looks unintentional—likely a copy-paste artifact from a previous edit. A quick trim to a single instance would tidy things up nicely. Not blocking the Mermaid changes, but worth a quick fix if you're passing through.
scripts/README.md (1)
31-64: LGTM!Also applies to: 401-425
tests/README.md (2)
72-105: LGTM!Also applies to: 198-221, 225-260
370-379: ⚡ Quick winTreble footer alert! 📋
Same footer duplication spotted here—"Built by 🧱 LightSpeedWP..." appears three times consecutively (lines 370–379). Appears to be a systematic issue across multiple README files in this PR. A quick trim to a single instance would restore polish. Likely a find-and-replace artifact, but worth a final pass to catch these.
.github/prompts/update-mermaid-diagrams.prompt.md (1)
4-122: LGTM!.github/reports/mermaid/colour-contrast-report-2026-06-18.md (1)
1-43: LGTM!package.json (1)
108-113: LGTM!scripts/validation/validate-mermaid-syntax.js (1)
3-3: LGTM!Also applies to: 16-24, 36-36, 61-61, 190-190, 280-280
scripts/validation/validate-mermaid-accessibility.js (1)
3-3: LGTM!Also applies to: 16-24, 50-50, 136-140, 273-273
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
.github/workflows/readme-audit.yml (2)
91-101:⚠️ Potential issue | 🟠 Major | ⚡ Quick winValidator jobs run before dependencies are installed.
These jobs execute
npm run validate:*, but there is nonpm cistep in the shown job setup. That can fail immediately on module imports (for exampleglob).Suggested patch
- name: Set up Node.js uses: actions/setup-node@v4 with: node-version: "18" cache: "npm" + - name: Install dependencies + run: npm ciAlso applies to: 118-120, 136-137
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-audit.yml around lines 91 - 101, The readme-audit.yml workflow is missing a dependency installation step before running validation commands. Add an `npm ci` step between the "Set up Node.js" step and the "Validate Mermaid diagrams" step (and apply the same fix to the other affected validation jobs mentioned at lines 118-120 and 136-137). This ensures that npm dependencies like glob are installed before any npm run validate commands are executed, preventing immediate module import failures during validation.
82-138:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd explicit least-privilege
permissionsfor these jobs.Nice workflow expansion overall — now let’s lock token scope down explicitly (read-only by default, elevate only where truly needed).
Suggested patch
validate-syntax: name: Validate Mermaid Syntax runs-on: ubuntu-latest + permissions: + contents: read @@ check-accessibility: name: Check WCAG Compliance runs-on: ubuntu-latest + permissions: + contents: read @@ check-contrast: name: Check Mermaid Colour Contrast runs-on: ubuntu-latest + permissions: + contents: readAs per coding guidelines, GitHub Actions workflows should use least-privilege permissions and default to read-only.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-audit.yml around lines 82 - 138, The three jobs validate-syntax, check-accessibility, and check-contrast are missing explicit least-privilege permissions blocks. Add a permissions section to each job setting contents to read, since these jobs only perform read operations on the repository (checking out code and running validation scripts without modifying anything). This follows the principle of defaulting to read-only access and only elevating permissions where truly needed.Sources: Coding guidelines, Linters/SAST tools
scripts/fix-mermaid-diagrams.js (1)
142-159:⚠️ Potential issue | 🟠 Major | ⚡ Quick winBroaden metadata detection to avoid duplicate
accTitle/accDescrentriesQuick gremlin on Line 142 and Line 157: the fixer only detects
accTitle:/accDescr:. Valid forms likeaccTitle My titleandaccDescr { ... }are treated as missing, so duplicate accessibility fields can be injected.Suggested patch
- if (!nextDiagram.includes("accTitle:")) { + const hasAccTitle = + /(?:^|\n)\s*accTitle(?:\s*[:=]|\s+)/m.test(nextDiagram); + if (!hasAccTitle) { const firstLine = nextDiagram.split("\n")[0]; @@ - if (!nextDiagram.includes("accDescr:")) { + const hasAccDescr = + /(?:^|\n)\s*accDescr(?:\s*[:=]|\s*{|\s+)/m.test(nextDiagram); + if (!hasAccDescr) { nextDiagram = `${nextDiagram}\naccDescr: Detailed diagram`; modified = true; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/fix-mermaid-diagrams.js` around lines 142 - 159, The accessibility metadata detection is too narrow - the includes() checks for "accTitle:" and "accDescr:" on lines 142 and 157 only match one specific format, but mermaid allows alternative formats like "accTitle My title" (without colon) and "accDescr { ... }" (with braces). Broaden both detection checks to match any occurrence of the metadata field name itself rather than just the colon-suffixed variants, so that existing accessibility metadata in alternative formats is properly detected and duplicate entries are not injected. Consider using regex or multiple include checks to catch all valid variations of these fields.
🧹 Nitpick comments (1)
.github/workflows/readme-audit.yml (1)
88-90: ⚡ Quick winHarden checkout steps by disabling credential persistence.
For pure validation jobs, set
persist-credentials: falseonactions/checkoutto reduce accidental token exposure paths.Suggested patch
- name: Checkout repository uses: actions/checkout@v4 + with: + persist-credentials: falseAs per coding guidelines, workflow security checks should include safe secret handling and minimised credential exposure.
Also applies to: 109-111, 127-129
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-audit.yml around lines 88 - 90, The actions/checkout@v4 steps in the readme-audit workflow do not disable credential persistence, increasing the risk of accidental token exposure. Add the `persist-credentials: false` configuration parameter to all three instances of the actions/checkout@v4 step (the one at the specified location and the two additional instances noted in the comment) to minimize credential exposure during the validation job execution, as per security guidelines for pure validation workflows.Sources: Coding guidelines, Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/reports/mermaid-accessibility-report.md:
- Line 3: Update the description text in the accessibility report to reflect the
current number of diagrams being audited. Change "all 24 Mermaid diagrams" to
"all 60 Mermaid diagrams" in the description field to ensure consistency between
the documentation and the actual audit scope. This simple numeric update will
prevent confusion about the audit coverage.
- Line 35: In the mermaid-accessibility-report.md file, locate the heading "##
Files Analyzed" and change the spelling from "Analyzed" (US English) to
"Analysed" (UK English) to comply with the repository's documentation standards
that require UK English spelling throughout all markdown and text files.
In @.github/reports/mermaid-validation-report.md:
- Line 3: Update the description field in the frontmatter at line 3 of the
mermaid-validation-report.md file. The current description states the validation
results are "for repository README files" but the report scope has expanded to
cover all Markdown and MDX files across the repository. Replace the
README-specific wording with text that accurately reflects the repo-wide scope
of the validation audit.
- Line 24: In the mermaid-validation-report.md file, change the section heading
"## Files Analyzed" to "## Files Analysed" to comply with UK English spelling
standards as required by the project's coding guidelines for markdown files.
This ensures consistency with other UK English terms used throughout the
documentation.
In @.github/workflows/readme-update.yml:
- Around line 70-74: The "Validate Mermaid colour contrast" step currently has
continue-on-error set to true, which allows the workflow to pass even when the
npm run validate:mermaid-contrast command fails. Remove the continue-on-error:
true line from this step to make the contrast validation blocking, ensuring that
non-compliant Mermaid diagrams will cause the workflow to fail and prevent the
commit from proceeding.
In `@instructions/mermaid.instructions.md`:
- Line 16: The instructions at line 16 claim that the validation workflow
"enforces the accessibility and syntax rules automatically," but this is
inaccurate. The provided validator and fixer snippets only enforce the presence
of `accTitle` and `accDescr` attributes without enforcing their proper placement
within the `---` header wrapper block format or preventing duplicate inline
declarations. Revise the claim on line 16 to accurately reflect what is actually
enforced by the current tooling, or update the validator/fixer snippets to fully
enforce header-block placement and duplicate-inline constraints. The same
accuracy issue applies to the rules mentioned around lines 68-71, so update
those as well to match the actual enforcement behavior.
- Around line 38-47: The outer fenced code blocks use triple backticks which can
conflict with the inner mermaid code blocks that also use triple backticks,
causing the outer block to terminate prematurely in Markdown renderers. Change
all outer fences from triple backticks (```text) to four backticks (````text) to
properly contain the inner mermaid blocks with their triple backticks. Apply
this change to all occurrences where mermaid examples are nested within text
fences throughout the document, including multiple instances.
- Around line 14-224: The mermaid.instructions.md file does not follow the
required instruction file template structure. Restructure the file to follow the
mandated pattern: start with a Role section, then add Overview, General Rules,
Detailed Guidance, Examples, Validation, and References/Cross-References
sections. Consolidate existing content like "When to Include a Diagram",
"Required Structure", "Diagram Types", "Colour Palette", "Theme Initialisation",
"Emoji in Node Labels", and "Layout and Clarity" into the appropriate sections
(most should fall under General Rules and Detailed Guidance). Ensure the
Validation section includes the npm commands already present. Add a new
References/Cross-References section at the end to link to related documentation
or files.
- Around line 4-11: The frontmatter in the mermaid.instructions.md file is
missing three canonical metadata keys required for all instructions/** files.
Add the missing keys file_type, domain, and stability to the frontmatter
section. The file_type should indicate this is an instruction file, domain
should categorize the subject area (likely "documentation" or "diagrams"), and
stability should indicate the maturity level of the instruction. Ensure all keys
in the canonical pattern (file_type, version, last_updated, owners, tags,
status, domain, stability) are present in the frontmatter block.
In `@scripts/validation/validate-mermaid-colour-contrast.js`:
- Around line 154-161: The validator currently extracts and stores only `fill`
and `color` properties but does not parse or validate the `stroke` property,
which is required as part of the documented fill+color+stroke triple. Extend the
regex matching logic in the section where fillMatch and colorMatch are defined
to also extract the stroke value using a similar pattern. Then update the
validation logic (referenced in the "Also applies to" range at lines 170-225) to
enforce that all three properties (fill, color, and stroke) must be present
together before marking a node as valid, rather than allowing partial matches to
pass validation.
- Around line 176-177: When parseColour(fill) or parseColour(color) returns a
falsy value (indicating an invalid or unsupported color), instead of silently
returning with no issues reported, add an issue entry to the issues array
describing that the color value is invalid or unsupported. This fix should be
applied in two places: when fillHex is falsy after calling parseColour(fill),
and when colorHex is falsy after calling parseColour(color) around the code
region mentioned as also applying to lines 212-214. Each case should push a
descriptive issue object to the issues array before returning it, rather than
returning early with no warnings about the unparseable color values.
---
Outside diff comments:
In @.github/workflows/readme-audit.yml:
- Around line 91-101: The readme-audit.yml workflow is missing a dependency
installation step before running validation commands. Add an `npm ci` step
between the "Set up Node.js" step and the "Validate Mermaid diagrams" step (and
apply the same fix to the other affected validation jobs mentioned at lines
118-120 and 136-137). This ensures that npm dependencies like glob are installed
before any npm run validate commands are executed, preventing immediate module
import failures during validation.
- Around line 82-138: The three jobs validate-syntax, check-accessibility, and
check-contrast are missing explicit least-privilege permissions blocks. Add a
permissions section to each job setting contents to read, since these jobs only
perform read operations on the repository (checking out code and running
validation scripts without modifying anything). This follows the principle of
defaulting to read-only access and only elevating permissions where truly
needed.
In `@scripts/fix-mermaid-diagrams.js`:
- Around line 142-159: The accessibility metadata detection is too narrow - the
includes() checks for "accTitle:" and "accDescr:" on lines 142 and 157 only
match one specific format, but mermaid allows alternative formats like "accTitle
My title" (without colon) and "accDescr { ... }" (with braces). Broaden both
detection checks to match any occurrence of the metadata field name itself
rather than just the colon-suffixed variants, so that existing accessibility
metadata in alternative formats is properly detected and duplicate entries are
not injected. Consider using regex or multiple include checks to catch all valid
variations of these fields.
---
Nitpick comments:
In @.github/workflows/readme-audit.yml:
- Around line 88-90: The actions/checkout@v4 steps in the readme-audit workflow
do not disable credential persistence, increasing the risk of accidental token
exposure. Add the `persist-credentials: false` configuration parameter to all
three instances of the actions/checkout@v4 step (the one at the specified
location and the two additional instances noted in the comment) to minimize
credential exposure during the validation job execution, as per security
guidelines for pure validation workflows.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: e58fccc6-6e29-426e-970e-235adb63d73e
⛔ Files ignored due to path filters (1)
.github/reports/mermaid-diagram-accessibility-spreadsheet.csvis excluded by!**/*.csv
📒 Files selected for processing (29)
.github/ISSUE_TEMPLATE/README.md.github/README.md.github/instructions/.archive/frontmatter.instructions.md.github/instructions/.archive/tests.instructions.md.github/prompts/update-mermaid-diagrams.prompt.md.github/reports/mermaid-accessibility-report.md.github/reports/mermaid-validation-report.md.github/reports/mermaid/colour-contrast-report-2026-06-18.md.github/reports/mermaid/diagram-validation-2025-12-11.md.github/workflows/readme-audit.yml.github/workflows/readme-update.yml.vscode/README.mdCONTRIBUTING.mdREADME.mddocs/AGENT_CREATION.mddocs/HUSKY_PRECOMMITS.mdinstructions/automation.instructions.mdinstructions/documentation-formats.instructions.mdinstructions/linting.instructions.mdinstructions/mermaid.instructions.mdinstructions/quality-assurance.instructions.mdpackage.jsonprofile/README.mdscripts/README.mdscripts/fix-mermaid-diagrams.jsscripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-colour-contrast.jsscripts/validation/validate-mermaid-syntax.jstests/README.md
📜 Review details
🔇 Additional comments (25)
instructions/documentation-formats.instructions.md (2)
502-518: 💤 Low valueMinor wording refinement: "Colour" already used in guidance text.
Line 502 correctly uses UK English "colours" in the prose. The colour values in the classDef declarations (lines 513–514) appear to follow the approved palette pattern (e.g.,
fill:#dcfce7,color:#14532d,stroke:#14532d`` for success). This aligns with the WCAG 2.2 AA approved palette referenced in the PR objectives.
404-405: LGTM!Also applies to: 419-420, 433-434, 455-456, 476-477, 547-548
instructions/automation.instructions.md (1)
81-82: LGTM!Also applies to: 669-670
instructions/linting.instructions.md (1)
105-106: LGTM!Also applies to: 141-142
instructions/quality-assurance.instructions.md (1)
80-96: LGTM!Also applies to: 377-378
CONTRIBUTING.md (1)
33-34: LGTM!docs/AGENT_CREATION.md (1)
111-112: LGTM!Also applies to: 149-151, 185-186, 218-219, 308-309, 353-354, 405-406, 478-479, 528-529
docs/HUSKY_PRECOMMITS.md (1)
119-120: LGTM!.github/instructions/.archive/frontmatter.instructions.md (1)
86-87: LGTM!.github/instructions/.archive/tests.instructions.md (1)
87-94: LGTM!Also applies to: 99-115, 180-195
.github/reports/mermaid/diagram-validation-2025-12-11.md (1)
282-290: LGTM!README.md (2)
127-217: 💤 Low valueAcclamation to the colour palette update! 🎨
The repository architecture diagram receives all the accessibility love—
accTitleandaccDescrproperly positioned, and the approved WCAG 2.2 AA colour palette applied consistently. The diagram legibility remains excellent across all node types.One tiny finesse: lines 228-229 and 351-352 show slightly different
accDescrformatting styles (inline vs. block). Whilst both render correctly, standardising to a single format (inline, as most diagrams use) would improve consistency across the entire file. Not blocking, but worth a future polish pass!Source: Coding guidelines
170-180: LGTM!Also applies to: 250-254, 296-300, 411-414
.github/README.md (1)
64-123: 💤 Low valueBrilliant accessibility enhancements across the .github hub documentation! 🌟
All three diagrams now sport proper
accTitleandaccDescrmetadata, and the WCAG 2.2 AA colour palette is applied with consistent contrast ratios. The diagrams remain visually engaging whilst remaining accessible to all users.One stylistic note: You'll notice some diagrams use inline
accDescr: "..."format (lines 216, 266) whilst others use the block formataccDescr { ... }(lines 71-73). Both are valid Mermaid syntax, but standardising to one format across all files in the PR would improve consistency. The inline format is more compact; the block format is clearer for longer descriptions. Current state isn't a blocker, but worth a polish pass across the repository-wide changes.Also applies to: 215-235, 265-323, 406-461
.github/ISSUE_TEMPLATE/README.md (1)
48-79: LGTM!profile/README.md (2)
34-71: LGTM!Also applies to: 95-129, 148-202, 225-244
301-308: ⚡ Quick winSpot of duplication in the footer! 🎯
The lovely "Made with 💚 by LightSpeedWP" footer message appears three times consecutively (lines 301–308). This looks unintentional—likely a copy-paste artifact from a previous edit. A quick trim to a single instance would tidy things up nicely. Not blocking the Mermaid changes, but worth a quick fix if you're passing through.
scripts/README.md (1)
31-64: LGTM!Also applies to: 401-425
tests/README.md (2)
72-105: LGTM!Also applies to: 198-221, 225-260
370-379: ⚡ Quick winTreble footer alert! 📋
Same footer duplication spotted here—"Built by 🧱 LightSpeedWP..." appears three times consecutively (lines 370–379). Appears to be a systematic issue across multiple README files in this PR. A quick trim to a single instance would restore polish. Likely a find-and-replace artifact, but worth a final pass to catch these.
.github/prompts/update-mermaid-diagrams.prompt.md (1)
4-122: LGTM!.github/reports/mermaid/colour-contrast-report-2026-06-18.md (1)
1-43: LGTM!package.json (1)
108-113: LGTM!scripts/validation/validate-mermaid-syntax.js (1)
3-3: LGTM!Also applies to: 16-24, 36-36, 61-61, 190-190, 280-280
scripts/validation/validate-mermaid-accessibility.js (1)
3-3: LGTM!Also applies to: 16-24, 50-50, 136-140, 273-273
🛑 Comments failed to post (11)
.github/reports/mermaid-accessibility-report.md (2)
3-3:
⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAlign the description with the current diagram count
Line 3 still says "all 24 Mermaid diagrams", but this report now records 60. Tiny text mismatch, big audit confusion later.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/reports/mermaid-accessibility-report.md at line 3, Update the description text in the accessibility report to reflect the current number of diagrams being audited. Change "all 24 Mermaid diagrams" to "all 60 Mermaid diagrams" in the description field to ensure consistency between the documentation and the actual audit scope. This simple numeric update will prevent confusion about the audit coverage.
35-35:
⚠️ Potential issue | 🟡 Minor | ⚡ Quick winSwitch heading to UK English spelling
Line 35 uses "Analyzed"; please use "Analysed" to match repo language standards.
As per coding guidelines,
**/*.{md,markdown,txt,instructions.md}requires UK English throughout (e.g., “optimise, organisation, colour, behaviour”).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/reports/mermaid-accessibility-report.md at line 35, In the mermaid-accessibility-report.md file, locate the heading "## Files Analyzed" and change the spelling from "Analyzed" (US English) to "Analysed" (UK English) to comply with the repository's documentation standards that require UK English spelling throughout all markdown and text files.Source: Coding guidelines
.github/reports/mermaid-validation-report.md (2)
3-3:
⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate scope wording in frontmatter description
Line 3 still says results are for repository README files, but this report now audits a repo-wide Markdown/MDX set. The description should match the actual scope.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/reports/mermaid-validation-report.md at line 3, Update the description field in the frontmatter at line 3 of the mermaid-validation-report.md file. The current description states the validation results are "for repository README files" but the report scope has expanded to cover all Markdown and MDX files across the repository. Replace the README-specific wording with text that accurately reflects the repo-wide scope of the validation audit.
24-24:
⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse UK spelling in the section heading
Line 24 uses "Files Analyzed"; please use "Files Analysed" for consistency with UK English standards.
As per coding guidelines,
**/*.{md,markdown,txt,instructions.md}requires UK English throughout (e.g., “optimise, organisation, colour, behaviour”).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/reports/mermaid-validation-report.md at line 24, In the mermaid-validation-report.md file, change the section heading "## Files Analyzed" to "## Files Analysed" to comply with UK English spelling standards as required by the project's coding guidelines for markdown files. This ensures consistency with other UK English terms used throughout the documentation.Source: Coding guidelines
.github/workflows/readme-update.yml (1)
70-74:
⚠️ Potential issue | 🟠 Major | ⚡ Quick winMake contrast validation blocking before commit/push
Line 73 currently lets contrast validation fail softly, which means non-compliant Mermaid updates can still sail through and be committed. For a WCAG gate, this should fail hard.
Suggested patch
- name: Validate Mermaid colour contrast if: ${{ env.UPDATE_SCOPE == 'all' || env.UPDATE_SCOPE == 'mermaid' }} run: npm run validate:mermaid-contrast - continue-on-error: true📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.- name: Validate Mermaid colour contrast if: ${{ env.UPDATE_SCOPE == 'all' || env.UPDATE_SCOPE == 'mermaid' }} run: npm run validate:mermaid-contrast🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/readme-update.yml around lines 70 - 74, The "Validate Mermaid colour contrast" step currently has continue-on-error set to true, which allows the workflow to pass even when the npm run validate:mermaid-contrast command fails. Remove the continue-on-error: true line from this step to make the contrast validation blocking, ensuring that non-compliant Mermaid diagrams will cause the workflow to fail and prevent the commit from proceeding.instructions/mermaid.instructions.md (4)
4-11:
⚠️ Potential issue | 🟠 Major | ⚡ Quick winFrontmatter is missing canonical instruction metadata keys.
Quick compliance win: this header should include the canonical
file_type,domain, andstabilitykeys forinstructions/**files.Suggested patch
description: "Design, accessibility, colour contrast, and validation standards for Mermaid diagrams across the repository" +file_type: "instruction" scope: "repo-local" version: "v2.0" last_updated: "2026-06-18" owners: ["LightSpeed Team"] tags: ["mermaid", "diagrams", "documentation", "a11y", "wcag", "colour-contrast", "visuals", "architecture"] applyTo: ["**/*.md", "**/*.mdx"] status: "active" +domain: "documentation" +stability: "stable"As per coding guidelines,
instructions/**must use the canonical frontmatter pattern(file_type, version, last_updated, owners, tags, status, domain, stability).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.description: "Design, accessibility, colour contrast, and validation standards for Mermaid diagrams across the repository" file_type: "instruction" scope: "repo-local" version: "v2.0" last_updated: "2026-06-18" owners: ["LightSpeed Team"] tags: ["mermaid", "diagrams", "documentation", "a11y", "wcag", "colour-contrast", "visuals", "architecture"] applyTo: ["**/*.md", "**/*.mdx"] status: "active" domain: "documentation" stability: "stable"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@instructions/mermaid.instructions.md` around lines 4 - 11, The frontmatter in the mermaid.instructions.md file is missing three canonical metadata keys required for all instructions/** files. Add the missing keys file_type, domain, and stability to the frontmatter section. The file_type should indicate this is an instruction file, domain should categorize the subject area (likely "documentation" or "diagrams"), and stability should indicate the maturity level of the instruction. Ensure all keys in the canonical pattern (file_type, version, last_updated, owners, tags, status, domain, stability) are present in the frontmatter block.Source: Coding guidelines
14-224:
⚠️ Potential issue | 🟠 Major | ⚡ Quick winInstruction file structure does not follow the required template headings.
This file currently uses custom section names, but
**/*.instructions.mdrequires an explicit pattern: role declaration +Overview+General Rules+Detailed Guidance+Examples+Validation+References/Cross-References.As per coding guidelines, instruction files must follow the mandated section pattern and include a references/cross-references section.
🧰 Tools
🪛 LanguageTool
[misspelling] ~24-~24: This word is normally spelled as one.
Context: ... when the documentation describes: - A multi-step process or workflow - Component relatio...(EN_COMPOUNDS_MULTI_STEP)
[uncategorized] ~30-~30: Possible missing comma found.
Context: ...dule Do not force a diagram into a file where a simple list or paragraph is cle...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~132-~132: Would you like to use the Oxford spelling “Initialization”? The spelling ‘Initialisation’ is also correct.
Context: ...alone to convey meaning. --- ## Theme Initialisation Use a theme init block only when there...(OXFORD_SPELLING_Z_NOT_S)
[style] ~166-~166: Would you like to use the Oxford spelling “Organization”? The spelling ‘Organisation’ is also correct.
Context: ... service | 🌐 |[🌐 External API]| | Organisation | 🏛️ |[🏛️ .github Hub]| | Tests |...(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~166-~166: The official name of this software platform is spelled with a capital “H”.
Context: ...External API]| | Organisation | 🏛️ |[🏛️ .github Hub]| | Tests | 🧪 |[🧪 Test Suite]...(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@instructions/mermaid.instructions.md` around lines 14 - 224, The mermaid.instructions.md file does not follow the required instruction file template structure. Restructure the file to follow the mandated pattern: start with a Role section, then add Overview, General Rules, Detailed Guidance, Examples, Validation, and References/Cross-References sections. Consolidate existing content like "When to Include a Diagram", "Required Structure", "Diagram Types", "Colour Palette", "Theme Initialisation", "Emoji in Node Labels", and "Layout and Clarity" into the appropriate sections (most should fall under General Rules and Detailed Guidance). Ensure the Validation section includes the npm commands already present. Add a new References/Cross-References section at the end to link to related documentation or files.Source: Coding guidelines
16-16:
⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift“Automatically enforced” is stricter than current tooling behaviour.
Line 16/rules imply header-block placement and duplicate-inline constraints are enforced, but the provided validator/fixer snippets only enforce presence of
accTitle/accDescrand can inject them without the---header wrapper. That can produce false confidence in compliance.Also applies to: 68-71
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@instructions/mermaid.instructions.md` at line 16, The instructions at line 16 claim that the validation workflow "enforces the accessibility and syntax rules automatically," but this is inaccurate. The provided validator and fixer snippets only enforce the presence of `accTitle` and `accDescr` attributes without enforcing their proper placement within the `---` header wrapper block format or preventing duplicate inline declarations. Revise the claim on line 16 to accurately reflect what is actually enforced by the current tooling, or update the validator/fixer snippets to fully enforce header-block placement and duplicate-inline constraints. The same accuracy issue applies to the rules mentioned around lines 68-71, so update those as well to match the actual enforcement behavior.
38-47:
⚠️ Potential issue | 🟡 Minor | ⚡ Quick winNested fenced examples should use four-backtick outer fences.
Using triple backticks for both outer (
text) and inner (mermaid) fences can terminate the outer block early in Markdown renderers.Suggested patch
-```text +````text ```mermaid --- accTitle: Short accessible title (max 80 chars) accDescr: Single-sentence description for simple diagrams --- flowchart LR ...-```
+````</details> As per coding guidelines, all Markdown documentation must follow formatting standards. Also applies to: 51-64 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@instructions/mermaid.instructions.mdaround lines 38 - 47, The outer fenced
code blocks use triple backticks which can conflict with the inner mermaid code
blocks that also use triple backticks, causing the outer block to terminate
prematurely in Markdown renderers. Change all outer fences from triple backticks
(```text) to four backticks (````text) to properly contain the inner mermaid
blocks with their triple backticks. Apply this change to all occurrences where
mermaid examples are nested within text fences throughout the document,
including multiple instances.</details> <!-- fingerprinting:phantom:poseidon:hawk --> <!-- cr-comment:v1:28bf85f315ebbf58ace4ce51 --> _Source: Coding guidelines_ <!-- This is an auto-generated comment by CodeRabbit --> </blockquote></details> <details> <summary>scripts/validation/validate-mermaid-colour-contrast.js (2)</summary><blockquote> 154-161: _⚠️ Potential issue_ | _🟠 Major_ | _⚡ Quick win_ **The validator does not enforce the required `fill` + `color` + `stroke` triple.** Current parsing/validation checks `fill` and `color` only. Declarations with `fill` but missing `stroke` still pass, which drifts from the documented standard. <details> <summary>Suggested patch</summary> ```diff - const colorMatch = props.match(/(?<!-)\bcolor\s*:\s*([^,;\s]+)/i); + const colorMatch = props.match(/(?<!-)\bcolor\s*:\s*([^,;\s]+)/i); + const strokeMatch = props.match(/(?<!-)\bstroke\s*:\s*([^,;\s]+)/i); @@ fill: fillMatch ? fillMatch[1].trim() : null, color: colorMatch ? colorMatch[1].trim() : null, + stroke: strokeMatch ? strokeMatch[1].trim() : null, @@ - const { kind, nodeId, fill, color } = styleDecl; + const { kind, nodeId, fill, color, stroke } = styleDecl; @@ + if (!stroke) { + issues.push({ + level: "error", + message: `${kind} "${nodeId}": fill ${fill} is missing explicit stroke:.`, + }); + } ``` </details> Also applies to: 170-225 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/validation/validate-mermaid-colour-contrast.js` around lines 154 - 161, The validator currently extracts and stores only `fill` and `color` properties but does not parse or validate the `stroke` property, which is required as part of the documented fill+color+stroke triple. Extend the regex matching logic in the section where fillMatch and colorMatch are defined to also extract the stroke value using a similar pattern. Then update the validation logic (referenced in the "Also applies to" range at lines 170-225) to enforce that all three properties (fill, color, and stroke) must be present together before marking a node as valid, rather than allowing partial matches to pass validation. ``` </details> <!-- fingerprinting:phantom:poseidon:hawk --> <!-- cr-comment:v1:eb9221c6c2ed2d18d4a4ce81 --> <!-- This is an auto-generated comment by CodeRabbit --> --- 176-177: _⚠️ Potential issue_ | _🟠 Major_ | _⚡ Quick win_ **Unsupported/invalid colour values currently pass silently.** If `fill` or `color` cannot be parsed, the validator returns no issue, which can hide real contrast problems. <details> <summary>Suggested patch</summary> ```diff const fillHex = parseColour(fill); - if (!fillHex) return issues; + if (!fillHex) { + issues.push({ + level: "error", + message: `${kind} "${nodeId}": unsupported fill colour "${fill}". Use hex or a supported named colour.`, + }); + return issues; + } @@ const colorHex = parseColour(color); - if (!colorHex) return issues; + if (!colorHex) { + issues.push({ + level: "error", + message: `${kind} "${nodeId}": unsupported text colour "${color}". Use hex or a supported named colour.`, + }); + return issues; + } ``` </details> Also applies to: 212-214 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/validation/validate-mermaid-colour-contrast.js` around lines 176 - 177, When parseColour(fill) or parseColour(color) returns a falsy value (indicating an invalid or unsupported color), instead of silently returning with no issues reported, add an issue entry to the issues array describing that the color value is invalid or unsupported. This fix should be applied in two places: when fillHex is falsy after calling parseColour(fill), and when colorHex is falsy after calling parseColour(color) around the code region mentioned as also applying to lines 212-214. Each case should push a descriptive issue object to the issues array before returning it, rather than returning early with no warnings about the unparseable color values. ``` </details> <!-- fingerprinting:phantom:poseidon:hawk --> <!-- cr-comment:v1:f158f77818003f4608e4fe91 --> <!-- This is an auto-generated comment by CodeRabbit --> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
🔍 Reviewer Summary for PR #987CI Status: ❌ Recommendations
|
Mermaid diagrams WCAG 2.2 AA contrast sweep
Linked issues
Closes #986
Summary
accTitleandaccDescrheaders to every Mermaid diagram in the repository.Changelog
Changed
Fixed
Added
Removed
Risk Assessment
Risk Level: Low
Potential Impact: Documentation-only changes to Mermaid rendering and validation behaviour.
Mitigation Steps:
How to Test
Prerequisites
npm ci.Test Steps
npm run validate:mermaid.Expected Results
accTitleandaccDescr.Edge Cases to Verify
styleandclassDefdeclarations keep explicitfill,color, andstrokevalues.Checklist (Global DoD / PR)