docs(mermaid): repository-wide diagram colour sweep and content refresh#982
docs(mermaid): repository-wide diagram colour sweep and content refresh#982ashleyshaw wants to merge 13 commits into
Conversation
…standards Adds a new colour contrast validator, a PR-triggered workflow, and comprehensive mermaid diagram standards to address dark-mode contrast failures where fill-only style declarations render with white text (~1.1:1 contrast ratio) rather than the intended dark text. - scripts/validation/validate-mermaid-colour-contrast.js: new WCAG AA checker that detects fill declarations missing explicit color, calculates relative luminance and contrast ratio per the WCAG 2.2 formula, and produces a dated report under .github/reports/mermaid/ - .github/workflows/validate-mermaid-pr.yml: new workflow triggered on pull_request and feature branch pushes for any changed .md files; runs syntax, accessibility, and contrast checks; posts a summary comment on the PR and fails the build on contrast errors - instructions/mermaid.instructions.md: updated to v2.0 with approved WCAG AA colour palette (fill+color+stroke triples, all ≥ 4.5:1), canonical emoji vocabulary, Phosphor icon limitation note, required accTitle/accDescr header block structure, and repo-wide update process - package.json: adds validate:mermaid-contrast and validate:mermaid (runs all three validators in sequence) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
lint-staged@17.0.7 requires Node >=22.22.1; the previous node-version: 20 caused npm ci to fail with EBADENGINE on every run of validate-mermaid-pr. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
Validator fixes (scripts/validation/validate-mermaid-colour-contrast.js): - Hex regex now strictly matches 3 or 6 digits only; 4/5-digit strings previously caused NaN luminance and silent validation bypass - Negative lookbehind (?<!-) on fill/color prevents false positives from hyphenated CSS properties like stop-color or stroke-color - Missing-color logic now checks both light (#333333) and dark (#ffffff) modes independently, reporting the correct failure mode and eliminating duplicate warning+error entries for the same declaration - Line numbers (diagram.startLine + style.line) added to console output, findings array, and markdown report for precise file navigation Workflow fix (.github/workflows/validate-mermaid-pr.yml): - Changed-files step now uses heredoc syntax for GITHUB_OUTPUT; plain `echo "files=..."` failed with "Invalid format" on multi-line values Prompt update (.github/prompts/update-mermaid-diagrams.prompt.md): - Replaced empty stub with full instructions referencing v2.0 palette, correct validator commands, and per-diagram fix checklist Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
Update all Mermaid diagrams to v2.0 standards: - Replace fill-only style declarations with approved WCAG AA triples (fill + color + stroke) across README.md, profile/README.md, scripts/README.md, tests/README.md, docs/AGENT_CREATION.md, and .github/ISSUE_TEMPLATE/README.md - Consolidate all inline accTitle/accDescr attributes into the YAML header block format (before diagram type line) - Add missing accTitle/accDescr to 7 diagrams in docs/AGENT_CREATION.md - Convert legacy graph TD/TB/LR declarations to flowchart equivalents - Add accessibility header block to .github/ISSUE_TEMPLATE/README.md diagram - Include updated validator reports from all three validation scripts All three validators now pass at 100%: validate:mermaid-syntax — 17/17 diagrams valid validate:mermaid-accessibility — 23/23 diagrams accessible validate:mermaid-contrast — 0 errors, 0 warnings Closes #976 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
|
Warning Review limit reached
More reviews will be available in 50 minutes and 24 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 selected for processing (4)
📝 WalkthroughWalkthroughIntroduces a Node.js WCAG 2.2 AA colour contrast validator for Mermaid diagrams, wires it into ChangesMermaid WCAG AA Compliance Initiative
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant GHA as validate-mermaid-pr.yml
participant Scripts as npm validate scripts
participant Bot as PR Bot Comment
participant Artefacts as GitHub Artefacts
Dev->>GHA: push / pull_request on *.md
GHA->>GHA: compute changed files BASE..HEAD
GHA->>GHA: scan changed files for mermaid blocks
alt no mermaid blocks found
GHA-->>Dev: skip — no diagrams to check
else mermaid blocks present
GHA->>Scripts: validate:mermaid-syntax
GHA->>Scripts: validate:mermaid-accessibility
GHA->>Scripts: validate:mermaid-contrast
Scripts-->>GHA: syntax_ok, a11y_ok, contrast_ok outcomes
GHA->>Bot: post or update summary comment with icons
alt all_passed is false
GHA-->>Dev: exit 1 — job fails, merge blocked
else all_passed is true
GHA-->>Dev: job passes
end
GHA->>Artefacts: upload mermaid reports (retention 14 days)
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 |
🎨 Mermaid Diagram Validation✅ All Mermaid diagram checks passed.
|
🔍 Reviewer Summary for PR #982CI Status: ❌ Recommendations
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces v2.0 standards for Mermaid diagrams across the repository, focusing on WCAG 2.2 AA accessibility and colour contrast compliance. Key changes include updating the Mermaid instructions, adding a new validation script (validate-mermaid-colour-contrast.js) with corresponding npm scripts, and refactoring diagrams across multiple documentation files to use YAML-style accessibility headers and the approved high-contrast colour palette. Feedback on the changes suggests refactoring the eager globSync file scan in the new validation script into a lazy helper function to prevent unnecessary synchronous repository scans when validating specific changed files.
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.
- Bump version and last_updated in README.md, docs/AGENT_CREATION.md, profile/README.md, scripts/README.md, tests/README.md, and .github/ISSUE_TEMPLATE/README.md to pass front-matter-validate CI - Remove broken internal links to non-existent files (run-all-tests.sh, TEST_COVERAGE_SUMMARY.md, test-helper.bash, coverage/README.md, etc.) and redirect to existing targets to fix lint-and-links CI - Fix profile/README.md AI badge relative path (./. -> ../) - Add bare-URL patterns to .lycheeignore for LinkedIn and GNU GPL links that use standard Markdown syntax rather than autolinks Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
version and last_updated were stale on both generated reports, causing front-matter-validate to block the PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
./.github/custom-instructions.md resolves to profile/.github/... which doesn't exist. The correct path from profile/ is ../.github/custom-instructions.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
github-actions
Bot
added
status:needs-review
Satisfies the validate CI requirement — PR needs a CHANGELOG.md update documenting the repository-wide diagram palette sweep (#982). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 97a25e6dc4
ℹ️ 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".
| --- | ||
| accTitle: Short accessible title (max 80 chars) | ||
| accDescr: Single-sentence description for simple diagrams | ||
| --- |
There was a problem hiding this comment.
When diagrams follow this required structure, Mermaid treats the --- ... --- block as YAML frontmatter/configuration, not as accessibility syntax; the official accessibility syntax requires accTitle:/accDescr: keywords in the diagram text, and Mermaid configuration ignores invalid keys. As a result, the diagrams converted in this change can render without SVG <title>/<desc> even though the repo validator passes, so screen-reader users lose the descriptions. Move accTitle/accDescr back into the Mermaid body, or use supported title frontmatter plus accDescr in the body. Sources: https://mermaid.ai/open-source/config/accessibility.html and https://mermaid-js-mermaid.mintlify.app/concepts/configuration
Useful? React with 👍 / 👎.
coderabbitai
Bot
added
area:a11y
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/workflows/validate-mermaid-pr.yml:
- Around line 32-35: The "Checkout repository" step uses actions/checkout@v4
without explicitly disabling persisted credentials, which keeps Git credentials
in the local repo config and violates the least-privilege security principle.
Add a persist-credentials parameter set to false in the with section of the
checkout action to ensure that Git credentials are not persisted in the local
repository configuration after the checkout completes.
In `@scripts/validation/validate-mermaid-colour-contrast.js`:
- Around line 36-47: The glob pattern in the getMarkdownFiles function currently
only matches .md files using **/*.md, but it needs to also include .mdx files
since the PR workflow validates both file types. Update the glob pattern to use
brace expansion syntax to match both .md and .mdx extensions, ensuring that MDX
files with Mermaid diagrams are included in the validation scan.
🪄 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: 599a4214-221a-42ca-95c4-64a9b9363796
⛔ Files ignored due to path filters (1)
.github/reports/mermaid-diagram-accessibility-spreadsheet.csvis excluded by!**/*.csv
📒 Files selected for processing (16)
.github/ISSUE_TEMPLATE/README.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/workflows/validate-mermaid-pr.yml.lycheeignoreCHANGELOG.mdREADME.mddocs/AGENT_CREATION.mdinstructions/mermaid.instructions.mdpackage.jsonprofile/README.mdscripts/README.mdscripts/validation/validate-mermaid-colour-contrast.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). (3)
- GitHub Check: coderabbit-gate
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (19)
**/*.{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
**/.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
**/*.{md,markdown,txt,instructions.md}
📄 CodeRabbit inference engine (CLAUDE.md)
Language: Use UK English throughout (optimise, organisation, colour, behaviour).
Files:
CHANGELOG.mdscripts/README.mddocs/AGENT_CREATION.mdprofile/README.mdREADME.mdtests/README.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:
CHANGELOG.mdscripts/README.mddocs/AGENT_CREATION.mdprofile/README.mdREADME.mdtests/README.mdinstructions/mermaid.instructions.md
CHANGELOG.md
⚙️ CodeRabbit configuration file
CHANGELOG.md: Review CHANGELOG.md:
- Confirm entries follow Keep a Changelog 1.1.0 format.
- Each entry under [Unreleased] must include a PR link and issue link.
- Verify entries use the correct section headings (Added, Changed, Fixed, Deprecated, Removed, Security, Documentation, Performance).
- Check UK English spelling throughout.
Files:
CHANGELOG.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-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-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-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-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-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-colour-contrast.js
.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/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/validate-mermaid-pr.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/AGENT_CREATION.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
**/*.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/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/mermaid.instructions.md
🪛 LanguageTool
.github/reports/mermaid-accessibility-report.md
[uncategorized] ~47-~47: The official name of this software platform is spelled with a capital “H”.
Context: ...ADME.md - .github/projects/README.md - .github/projects/active/openspec/README.md - .g...
(GITHUB)
[uncategorized] ~48-~48: The official name of this software platform is spelled with a capital “H”.
Context: ...b/projects/active/openspec/README.md - .github/projects/active/openspec/changes/test-c...
(GITHUB)
[uncategorized] ~49-~49: The official name of this software platform is spelled with a capital “H”.
Context: ...st-coverage-implementation/README.md - .github/projects/active/template-enforcement-go...
(GITHUB)
[uncategorized] ~50-~50: The official name of this software platform is spelled with a capital “H”.
Context: ...ate-enforcement-governance/README.md - .github/projects/active/template-enforcement-go...
(GITHUB)
[uncategorized] ~51-~51: The official name of this software platform is spelled with a capital “H”.
Context: ...governance/openspec-strict/README.md - .github/projects/active/test-coverage-implement...
(GITHUB)
[uncategorized] ~52-~52: The official name of this software platform is spelled with a capital “H”.
Context: ...st-coverage-implementation/README.md - .github/projects/active/test-coverage-implement...
(GITHUB)
[uncategorized] ~53-~53: The official name of this software platform is spelled with a capital “H”.
Context: ...ementation/openspec-strict/README.md - .github/projects/active/wave-5-documentation-au...
(GITHUB)
[uncategorized] ~54-~54: The official name of this software platform is spelled with a capital “H”.
Context: ...tion/issue-seed-2026-06-08/README.md - .github/projects/archived/awesome-github-site/R...
(GITHUB)
[uncategorized] ~55-~55: The official name of this software platform is spelled with a capital “H”.
Context: ...chived/awesome-github-site/README.md - .github/projects/archived/awesome-github-site/o...
(GITHUB)
[uncategorized] ~56-~56: The official name of this software platform is spelled with a capital “H”.
Context: ...esome-github-site/openspec/README.md - .github/projects/archived/awesome-github-site/p...
(GITHUB)
[uncategorized] ~57-~57: The official name of this software platform is spelled with a capital “H”.
Context: ...wesome-github-site/phase-1/README.md - .github/projects/archived/awesome-github-site/p...
(GITHUB)
[uncategorized] ~58-~58: The official name of this software platform is spelled with a capital “H”.
Context: ...wesome-github-site/phase-2/README.md - .github/projects/completed/adoption-workstream-...
(GITHUB)
[uncategorized] ~59-~59: The official name of this software platform is spelled with a capital “H”.
Context: ...tion-workstream-2026-05-26/README.md - .github/projects/completed/agent-skill-memory-p...
(GITHUB)
[uncategorized] ~60-~60: The official name of this software platform is spelled with a capital “H”.
Context: ...ill-memory-platform/issues/README.md - .github/projects/completed/awesome-github-site/...
(GITHUB)
[uncategorized] ~61-~61: The official name of this software platform is spelled with a capital “H”.
Context: ...pleted/awesome-github-site/README.md - .github/projects/completed/awesome-github-site/...
(GITHUB)
[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ...esome-github-site/openspec/README.md - .github/projects/completed/awesome-github-site/...
(GITHUB)
[uncategorized] ~63-~63: The official name of this software platform is spelled with a capital “H”.
Context: ...wesome-github-site/phase-1/README.md - .github/projects/completed/awesome-github-site/...
(GITHUB)
[uncategorized] ~64-~64: The official name of this software platform is spelled with a capital “H”.
Context: ...wesome-github-site/phase-2/README.md - .github/projects/completed/branch-governance-ha...
(GITHUB)
[uncategorized] ~65-~65: The official name of this software platform is spelled with a capital “H”.
Context: ...nance-hardening-2026-06-08/README.md - .github/projects/completed/branch-governance-ha...
(GITHUB)
[uncategorized] ~66-~66: The official name of this software platform is spelled with a capital “H”.
Context: ...2026-06-08/openspec-strict/README.md - .github/projects/completed/github-workflow-cons...
(GITHUB)
[uncategorized] ~67-~67: The official name of this software platform is spelled with a capital “H”.
Context: ...w-consolidation-2026-05-28/README.md - .github/projects/completed/github-workflow-cons...
(GITHUB)
[uncategorized] ~68-~68: The official name of this software platform is spelled with a capital “H”.
Context: ...lidation-2026-05-28/issues/README.md - .github/projects/completed/issue-35-instruction...
(GITHUB)
[uncategorized] ~69-~69: The official name of this software platform is spelled with a capital “H”.
Context: ...issue-35-instruction-audit/README.md - .github/projects/completed/issue-670-readme-ref...
(GITHUB)
[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...d/issue-670-readme-refresh/README.md - .github/projects/completed/label-governance-sta...
(GITHUB)
[uncategorized] ~71-~71: The official name of this software platform is spelled with a capital “H”.
Context: ...e-stabilisation-2026-05-27/README.md - .github/projects/completed/label-governance-sta...
(GITHUB)
[uncategorized] ~72-~72: The official name of this software platform is spelled with a capital “H”.
Context: ...lisation-2026-05-27/issues/README.md - .github/projects/completed/plugin-pack-waves/RE...
(GITHUB)
[uncategorized] ~73-~73: The official name of this software platform is spelled with a capital “H”.
Context: ...ompleted/plugin-pack-waves/README.md - .github/projects/completed/plugin-pack-waves/is...
(GITHUB)
[uncategorized] ~74-~74: The official name of this software platform is spelled with a capital “H”.
Context: ...d/plugin-pack-waves/issues/README.md - .github/projects/completed/plugin-pack-waves/op...
(GITHUB)
[uncategorized] ~75-~75: The official name of this software platform is spelled with a capital “H”.
Context: ...pack-waves/openspec-strict/README.md - .github/projects/completed/portable-ai-plugin-r...
(GITHUB)
[uncategorized] ~76-~76: The official name of this software platform is spelled with a capital “H”.
Context: ...-plugin-restructure/issues/README.md - .github/projects/completed/refactor-migrate-pro...
(GITHUB)
[uncategorized] ~77-~77: The official name of this software platform is spelled with a capital “H”.
Context: ...te-prompts/openspec-strict/README.md - .github/projects/completed/refactor-migrate-pro...
(GITHUB)
[uncategorized] ~78-~78: The official name of this software platform is spelled with a capital “H”.
Context: ...r-migrate-prompts/openspec/README.md - .github/projects/completed/root-cleanup-depende...
(GITHUB)
[uncategorized] ~79-~79: The official name of this software platform is spelled with a capital “H”.
Context: ...cy-audit-closed-2026-06-08/README.md - .github/projects/completed/root-cleanup-depende...
(GITHUB)
[uncategorized] ~80-~80: The official name of this software platform is spelled with a capital “H”.
Context: ...2026-06-08/openspec-strict/README.md - .github/projects/completed/wave-5-documentation...
(GITHUB)
[uncategorized] ~81-~81: The official name of this software platform is spelled with a capital “H”.
Context: ...on-audit-closed-2026-06-01/README.md - .github/prompts/README.md - .github/reports/REA...
(GITHUB)
[uncategorized] ~82-~82: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/prompts/README.md - .github/reports/README.md - .github/rulesets/RE...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/reports/README.md - .github/rulesets/README.md - .github/schemas/RE...
(GITHUB)
[uncategorized] ~84-~84: The official name of this software platform is spelled with a capital “H”.
Context: ...ADME.md - .github/rulesets/README.md - .github/schemas/README.md - .github/tests/fixtu...
(GITHUB)
[uncategorized] ~85-~85: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/schemas/README.md - .github/tests/fixtures/pr-templates/README.md -...
(GITHUB)
[uncategorized] ~86-~86: The official name of this software platform is spelled with a capital “H”.
Context: ...ests/fixtures/pr-templates/README.md - .github/workflows/README.md - .schemas/README.m...
(GITHUB)
.github/prompts/update-mermaid-diagrams.prompt.md
[uncategorized] ~19-~19: The official name of this software platform is spelled with a capital “H”.
Context: ...2.2 AA contrast checker - Workflow: .github/workflows/validate-mermaid-pr.yml — PR...
(GITHUB)
[style] ~82-~82: Would you like to use the Oxford spelling “Organization”? The spelling ‘Organisation’ is also correct.
Context: ... ❌ Failed,
(OXFORD_SPELLING_Z_NOT_S)
tests/README.md
[uncategorized] ~57-~57: The official name of this software platform is spelled with a capital “H”.
Context: ...chema/README.md](../schema/README.md), [tests workflow`](../.github/workflows/testing.yml) | ![Testing Bad...
(GITHUB)
[uncategorized] ~353-~353: The official name of this software platform is spelled with a capital “H”.
Context: ...amework - GitHub Actions Tests Workflow — CI/CD testing ...
(GITHUB)
instructions/mermaid.instructions.md
[misspelling] ~24-~24: This word is normally spelled as one.
Context: ...documentation file that 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] ~134-~134: Would you like to use the Oxford spelling “Initialization”? The spelling ‘Initialisation’ is also correct.
Context: ...e primary communicators. --- ## Theme Initialisation Include a theme init block only when y...
(OXFORD_SPELLING_Z_NOT_S)
[style] ~171-~171: 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] ~171-~171: The official name of this software platform is spelled with a capital “H”.
Context: ...External API]| | Organisation | 🏛️ |[🏛️ .github Hub]| | Tests | 🧪 |[🧪 Test Suite]...
(GITHUB)
[uncategorized] ~207-~207: The official name of this software platform is spelled with a capital “H”.
Context: ... (new) ``` The PR validation workflow (.github/workflows/validate-mermaid-pr.yml) run...
(GITHUB)
[uncategorized] ~255-~255: The official name of this software platform is spelled with a capital “H”.
Context: ...rmaid-syntax.js) — Syntax validator - [.github/workflows/validate-mermaid-pr.yml](../....
(GITHUB)
[uncategorized] ~255-~255: The official name of this software platform is spelled with a capital “H”.
Context: ...github/workflows/validate-mermaid-pr.yml](../.github/workflows/validate-mermaid-pr.yml) — PR...
(GITHUB)
🪛 zizmor (1.25.2)
.github/workflows/validate-mermaid-pr.yml
[warning] 32-35: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
[info] 83-83: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 119-119: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 120-120: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 121-121: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 138-138: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 139-139: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 140-140: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 195-195: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 196-196: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[info] 197-197: code injection via template expansion (template-injection): may expand into attacker-controllable code
(template-injection)
[error] 33-33: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)
(unpinned-uses)
[error] 38-38: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)
(unpinned-uses)
[error] 135-135: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)
(unpinned-uses)
[error] 202-202: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)
(unpinned-uses)
🔇 Additional comments (42)
package.json (1)
108-109: LGTM!instructions/mermaid.instructions.md (1)
1-256: LGTM!.github/prompts/update-mermaid-diagrams.prompt.md (1)
1-120: LGTM!README.md (7)
5-6: LGTM!
127-220: LGTM!
228-276: LGTM!
282-322: LGTM!
328-349: LGTM!
357-425: LGTM!
479-519: LGTM!profile/README.md (5)
5-7: LGTM!
26-26: LGTM!Also applies to: 34-73
97-133: LGTM!
151-208: LGTM!
230-252: LGTM!scripts/README.md (4)
5-6: LGTM!
31-91: LGTM!
403-431: LGTM!
459-459: ⚡ Quick winLink corrected to existing documentation.
Updated broken reference from
../tests/TEST_COVERAGE_SUMMARY.mdto../tests/README.md, aligning with current directory structure.tests/README.md (7)
5-6: LGTM!
57-57: LGTM!
72-107: LGTM!
200-225: LGTM!
229-266: LGTM!
330-330: LGTM!
353-353: LGTM!docs/AGENT_CREATION.md (9)
6-8: LGTM!
110-154: LGTM!
186-201: LGTM!
221-235: LGTM!
313-326: LGTM!
360-387: LGTM!
414-433: LGTM!
489-496: LGTM!
541-550: LGTM!.github/ISSUE_TEMPLATE/README.md (2)
6-6: LGTM!
48-81: LGTM!.github/reports/mermaid/colour-contrast-report-2026-06-18.md (1)
1-43: Confirm diagram count consistency across three validators.The colour-contrast report scanned 45 diagrams across 13 files, whilst the syntax validator reports 17 valid diagrams and the accessibility validator reports 23 diagrams. This ~2–3× discrepancy suggests the validators may be running on different file scopes or testing different diagram attributes. Verify that this is expected behaviour or investigate whether the scope mismatch indicates missing coverage.
Can you confirm whether these three counts reflect different validation scopes (e.g., colour-contrast checks all Mermaid blocks, syntax validates only diagram structure, accessibility checks only accTitle/accDescr) or if there's a scope drift that needs reconciliation?
.github/reports/mermaid-accessibility-report.md (1)
3-3: ⚡ Quick winUpdate description to reflect the new diagram count.
Line 3 still claims "all 24 Mermaid diagrams," but the Summary (line 30) reports 23 accessible diagrams. Update the frontmatter description to say "23" to keep metadata in sync with the actual findings.
🔧 Proposed fix
-description: Accessibility compliance audit of all 24 Mermaid diagrams for accTitle and accDescr attributes +description: Accessibility compliance audit of all 23 Mermaid diagrams for accTitle and accDescr attributes.github/reports/mermaid-validation-report.md (1)
20-23: Investigate diagram count alignment across validation reports.The syntax report shows 17 valid diagrams, the accessibility report shows 23 diagrams, and the colour-contrast report shows 45 diagrams. This three-way discrepancy needs clarification: are these validators intentionally testing different subsets of files, or is there scope drift? The PR objectives claim 45 diagrams updated across 10 files—confirm that each validator is testing the correct scope.
Can you verify:
- Which files should each validator scan? (The sync validator lists 32 files, accessibility lists ~50, colour-contrast lists 13.)
- Are the 45 diagrams from the PR objectives accounted for across these three counts?
- Should all three validators report the same file scope?
CHANGELOG.md (1)
34-34: CHANGELOG entry is well-formatted and complete.The Mermaid colour-contrast sweep entry follows Keep a Changelog 1.1.0 format, includes both PR (
#982) and issue (#977) links, and uses correct UK English spelling throughout. The entry accurately documents the scope, the approved palette introduction, and the validator dependency. No changes needed here..lycheeignore (1)
4-9: ⚡ Quick winRemove duplicate URL entries in .lycheeignore.
The file contains duplicate exclusions for social and external URLs in two different formats:
<https://twitter.com>andhttps://twitter.com(lines 4–5)<https://x.com>andhttps://x.com(lines 6–7)<https://www.linkedin.com>andhttps://www.linkedin.com(lines 8–9)<https://www.gnu.org/licenses/gpl-3.0>andhttps://www.gnu.org/licenses/gpl-3.0(lines 23–24)<https://www.w3.org/WAI/WCAG22/quickref/>andhttps://www.w3.org/WAI/WCAG22/quickref/(lines 27–28)Lychee typically requires only one entry per URL. Keep the angle-bracket format (lines 4, 6, 8, 23, 27), which appears to be the project's existing convention, and remove the plain-format duplicates.
🧹 Proposed cleanup
# Social platforms that block automated HTTP clients <https://twitter.com> -https://twitter.com <https://x.com> -https://x.com <https://www.linkedin.com> -https://www.linkedin.com # LightSpeed organisation websites — external, may have transient availability @@ -20,10 +20,10 @@ # External licence URL occasionally times out in CI link checks <https://www.gnu.org/licenses/gpl-3.0> -https://www.gnu.org/licenses/gpl-3.0 # W3C WCAG specification — reference link, occasionally times out in CI <https://www.w3.org/WAI/WCAG22/quickref/> -https://www.w3.org/WAI/WCAG22/quickref/Also applies to: 24-24, 28-28
- Add persist-credentials: false to checkout step (least-privilege)
- Extend glob pattern to **/*.{md,mdx} so MDX files with Mermaid diagrams
are included in default contrast validator scans
- Fix accessibility report description count (24 → 23)
Addresses CodeRabbit review comments on PR #982.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
|
@Mergifyio refresh |
✅ Pull request refreshed |
|
@Mergifyio queue |
Merge Queue Status
Waiting for any of
All conditions
|
2 participants
Linked issues
Closes #976
Summary
This PR updates every Mermaid diagram across the repository to conform with the v2.0 standards defined in
instructions/mermaid.instructions.md.Files changed: 6 documentation files + 4 validator report files
Diagrams updated: 45 diagrams scanned, all now passing all three validators at 100%.
What changed
Files with diagram updates
README.mdgraph TD→flowchart TD;flowchart TB→flowchart TDprofile/README.mdgraph TB→flowchart TDscripts/README.mdgraph TB→flowchart TDtests/README.mdgraph TB→flowchart TDdocs/AGENT_CREATION.mdgraph TB→flowchart TD; 7 additional diagrams: add missing accTitle/accDescr header blocks.github/ISSUE_TEMPLATE/README.mdChangelog
Changed
style X fill:#colourdeclarations with approved WCAG 2.2 AA colour triples (fill,color,stroke) from the canonical palette ininstructions/mermaid.instructions.mdaccTitle/accDescrattributes (placed after the diagram type line) into the YAML---header block format, as required by v2.0 standardsaccTitleandaccDescraccessibility attributes to 8 diagrams acrossdocs/AGENT_CREATION.mdand.github/ISSUE_TEMPLATE/README.mdgraph TD,graph TB, andgraph LRdeclarations to theirflowchartequivalents (flowchart TD,flowchart LR)flowchart TBdirections toflowchart TD.github/reports/mermaid/Validator results (post-change)
Checklist (Global DoD / PR)
{type}/{scope}-{short-title}naming conventiondevelop(notmain)accTitleandaccDescrin header block formatgraphdeclarations converted toflowchartCloses🤖 Generated with Claude Code
https://claude.ai/code/session_01LXjmeDonrDybfPZsH6Aa6w
Generated by Claude Code