fix(a11y): convert all Mermaid YAML header blocks to inline accTitle/accDescr syntax by ashleyshaw · Pull Request #995 · lightspeedwp/.github

ashleyshaw · 2026-06-19T06:13:06Z

Fix Pull Request

Linked issues

Closes #991

Summary

GitHub's embedded Mermaid renderer does not support YAML front-matter (--- blocks before the diagram type line). Diagrams using that format fail to render and show a parse error. The correct format places accTitle and accDescr as inline statements inside the diagram body, directly after the diagram type declaration.

This PR converts all affected Mermaid diagrams across the repository to the correct inline syntax and updates validation tooling and documentation to enforce it going forward.

Changes

Diagram fixes (YAML header → inline syntax):

.github/ISSUE_TEMPLATE/README.md — 1 diagram
.github/README.md — 4 diagrams
docs/AGENT_CREATION.md — 8 diagrams
docs/CANONICAL_CONFIGS_GUIDE.md — 2 diagrams
.vscode/README.md — 1 diagram
instructions/mermaid.instructions.md — code examples updated
.github/reports/audits/2026-06-03-file-organisation-migration-plan-673.md
.github/reports/audits/readme-audit-2026-05-31.md

Tooling and documentation:

scripts/validation/validate-mermaid-accessibility.js — now rejects diagrams where the first meaningful line is --- (YAML front-matter), with a clear error directing users to use inline syntax
instructions/mermaid.instructions.md — updated rules to explicitly forbid YAML --- front-matter and document the correct inline format
.github/prompts/update-mermaid-diagrams.prompt.md — rewritten to show correct inline format with explicit WRONG vs CORRECT examples
.github/reports/mermaid-accessibility-report.md — regenerated

Impact / Compatibility

Runtime/behaviour changes: None — accessibility metadata and documentation only
All affected diagrams now render correctly on GitHub
CI validate:mermaid-accessibility will now fail on any future YAML front-matter diagrams

Verification

validate:mermaid-accessibility passes (all diagrams use inline syntax)
All Mermaid diagrams render correctly (no YAML header parse errors)
Validation script rejects YAML front-matter format
Instructions and prompt updated with correct examples

Risk & Rollback

Risk level: Minimal — accessibility metadata and documentation only
Rollback plan: Revert commits

Changelog

Fixed

Converted all Mermaid --- YAML front-matter blocks to inline accTitle/accDescr syntax, which is the only format supported by GitHub's Mermaid renderer. Closes fix(a11y): ISSUE_TEMPLATE README.md Mermaid diagram missing YAML header block accTitle/accDescr #991.
Updated validate-mermaid-accessibility.js to reject YAML front-matter and provide actionable error messages.
Updated instructions/mermaid.instructions.md and Mermaid prompt to document and enforce the correct inline format.

Checklist (Global DoD / PR)

All AC met and demonstrated
Accessibility checklist completed: all diagrams now have valid accTitle and accDescr in supported format
Docs/readme/changelog updated
Security checklist completed: N/A
CI green; linked issues closed

Generated by Claude Code

coderabbitai · 2026-06-19T06:13:14Z

Warning

Review limit reached

@ashleyshaw, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes. 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 @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f25746cb-b3f2-42a3-9b07-0e841d87f0a1

📥 Commits

Reviewing files that changed from the base of the PR and between 443a6c2 and 4b44f89.

⛔ Files ignored due to path filters (1)

.github/reports/mermaid-diagram-accessibility-spreadsheet.csv is excluded by !**/*.csv

📒 Files selected for processing (4)

.github/labels.yml
.github/reports/mermaid-accessibility-report.md
CHANGELOG.md
scripts/agents/includes/label-sync.js

📝 Walkthrough

Walkthrough

The PR migrates all Mermaid diagrams repository-wide from a YAML --- front-matter header format (unsupported by GitHub's renderer) to inline accTitle/accDescr placement directly after the diagram type declaration. The validation script is updated to detect and reject the old format, and a regenerated validation report reflects 45 diagrams all passing.

Changes

Mermaid Accessibility Format Migration

Layer / File(s)	Summary
Inline `accTitle`/`accDescr` rule definition `instructions/mermaid.instructions.md`, `.github/prompts/update-mermaid-diagrams.prompt.md`	Rewrites accessibility guidance to require inline placement of `accTitle`/`accDescr` immediately after the diagram type line, explicitly forbids YAML `---` front-matter, updates all examples, and bumps version metadata.
Validator: YAML front-matter detection and inline checks `scripts/validation/validate-mermaid-accessibility.js`	Adds `/.claude/` glob exclusion, introduces early-exit detection when a Mermaid block opens with `---`, tightens `accTitle`/`accDescr` regex to inline-only forms, and improves the unclosed `accDescr { }` error message.
Diagram reformatting across all docs `docs/AGENT_CREATION.md`, `docs/CANONICAL_CONFIGS_GUIDE.md`, `.github/ISSUE_TEMPLATE/README.md`, `.github/README.md`, `.github/reports/audits/*`, `.vscode/README.md`	Applies the new inline `accTitle`/`accDescr` format to Mermaid blocks in all affected files and bumps front-matter version/date metadata in each.
Regenerated Mermaid validation report `.github/reports/mermaid-validation-report.md`	Updates the report with a new run timestamp, increases diagram count from 17 to 45, maintains a 100% pass rate, and expands the "Files Analysed" list to reflect repository-wide coverage.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

fix(a11y): ISSUE_TEMPLATE README.md Mermaid diagram missing YAML header block accTitle/accDescr #991: This PR directly addresses the issue by correcting the Mermaid accessibility metadata format — switching from YAML front-matter (identified as unsupported by GitHub's renderer) to the inline accTitle/accDescr placement, and updating the validator and documentation accordingly.

Possibly related PRs

lightspeedwp/.github#696: Overlaps directly with the validate-mermaid-accessibility.js changes, particularly the YAML front-matter detection and accTitle/accDescr validation logic.
lightspeedwp/.github#982: Both PRs modify Mermaid accessibility metadata conventions and update .github/prompts/update-mermaid-diagrams.prompt.md with revised accTitle/accDescr placement expectations.

Suggested labels

priority:normal, status:needs-review, lang:md, lang:js, type:bug, type:documentation, area:documentation, area:a11y, area:scripts

Suggested reviewers

krugazul

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly summarises the primary change: converting Mermaid YAML headers to inline accTitle/accDescr syntax, which directly addresses the accessibility issue being fixed.
Description check	✅ Passed	The PR description comprehensively covers all required template sections: linked issues (`#991`), clear summary of the problem, detailed change list, impact assessment, verification steps, risk evaluation, and changelog entries following the template structure.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/mermaid-inline-accessibility-syntax

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-06-19T06:13:42Z

Metadata governance

Item: fix(a11y): convert all Mermaid YAML header blocks to inline accTitle/accDescr syntax #995
Assignee: ashleyshaw
Milestone: fix(a11y): ISSUE_TEMPLATE README.md Mermaid diagram missing YAML header block `a
Linked issues/PRs: fix(a11y): ISSUE_TEMPLATE README.md Mermaid diagram missing YAML header block accTitle/accDescr #991

github-actions · 2026-06-19T06:13:51Z

🎨 Mermaid Diagram Validation

✅ All Mermaid diagram checks passed.

Check	Result
✅ Syntax (diagram type, direction, bracket matching)	Passed
✅ Accessibility (`accTitle` / `accDescr` present)	Passed
✅ Colour contrast (WCAG 2.2 AA ≥ 4.5:1)	Passed

github-actions · 2026-06-19T06:14:01Z

🔍 Reviewer Summary for PR #995

CI Status: ❌ success
Files changed: 16
Risk Distribution: 0 critical, 9 high, 0 medium, 7 low

Recommendations

⚠️ Database migration without rollback plan documented

…syntax GitHub's Mermaid renderer does not support the --- YAML front-matter block syntax (Mermaid v10.3+ feature). Diagrams with --- headers before the diagram type fail to render and show a parse error. Convert all affected diagrams to the supported inline syntax where accTitle and accDescr appear inside the diagram body, directly after the type declaration. Files fixed: - .github/ISSUE_TEMPLATE/README.md - .vscode/README.md - docs/AGENT_CREATION.md - docs/CANONICAL_CONFIGS_GUIDE.md - instructions/mermaid.instructions.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

Convert remaining --- YAML header syntax to inline accTitle/accDescr in two audit report files that had broken Mermaid diagram rendering. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

GitHub's renderer does not support YAML front-matter (--- blocks) in Mermaid diagrams. Convert all diagrams to use inline accTitle and accDescr statements after the diagram type declaration. Files fixed (YAML header removal): - .github/README.md — 4 diagrams (had inline attrs already; YAML headers removed) Documentation and tooling updates: - instructions/mermaid.instructions.md — rules updated to document inline syntax as required; explicitly forbids YAML --- front-matter - .github/prompts/update-mermaid-diagrams.prompt.md — rewritten to instruct inline format; includes clear WRONG vs CORRECT examples - scripts/validation/validate-mermaid-accessibility.js — now rejects diagrams that start with YAML --- front-matter and provides actionable error messages Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

Regenerated mermaid-accessibility-report.md and spreadsheet/validation reports to reflect the inline accTitle/accDescr syntax fixes across the repository. All diagrams now pass compliance validation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

gemini-code-assist

Code Review

This pull request standardizes Mermaid diagram accessibility by migrating from YAML front-matter headers to inline accTitle and accDescr attributes across all documentation and configuration files. The validation script has been updated to enforce this requirement and reject the unsupported YAML syntax. Feedback includes a recommendation to exclude the .claude/ directory from the validation scan to avoid processing temporary worktrees and a suggestion to improve the robustness of the block tracking logic using regex.

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.

…ouched files All files modified by the Mermaid YAML-header conversion commits require version and last_updated frontmatter updates per the validate:frontmatter:changed CI check. Also rebased onto develop to incorporate PR #994 changes. Gemini review fixes (validate-mermaid-accessibility.js): - Add **/.claude/** to globSync ignore list to skip Claude Code worktrees - Use regex /^accDescr\s*\{/ instead of startsWith('accDescr {') for robustness Files bumped: - .github/ISSUE_TEMPLATE/README.md: v1.7 → v1.8 (2026-06-19) - .github/README.md: 3.6 → 3.7 (2026-06-19) - .github/prompts/update-mermaid-diagrams.prompt.md: (2026-06-19) - .github/reports/audits/2026-06-03-…-673.md: v1.0.0 → v1.0.1 (2026-06-19) - .github/reports/mermaid-accessibility-report.md: 1.0.0 → 1.0.1 (2026-06-19) - .vscode/README.md: v1.3 → v1.4 (2026-06-19) - docs/AGENT_CREATION.md: v1.5 → v1.6 (2026-06-19) - docs/CANONICAL_CONFIGS_GUIDE.md: v1.0.2 → v1.0.3 (2026-06-19) - instructions/mermaid.instructions.md: v2.2 → v2.3 (2026-06-19) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

Documents the conversion of YAML front-matter blocks to inline accTitle/ accDescr syntax in all affected markdown files (PR #995, closes #991). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 443a6c2ce8

ℹ️ 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".

chatgpt-codex-connector · 2026-06-19T07:21:33Z

-.claude/worktrees/agent-ad0b044aa1f4b21f2/tests/README.md,2,sequenceDiagram,No,No,"Missing accTitle attribute; Missing accDescr attribute",⚠️ Non-Compliant
-.claude/worktrees/agent-ad0b044aa1f4b21f2/tests/README.md,3,flowchart,No,No,"Missing accTitle attribute; Missing accDescr attribute",⚠️ Non-Compliant
+File,Diagram Number,Diagram Type,Has accTitle,Has accDescr,Missing Attributes,Compliance Status
+.claude/worktrees/agent-af9d252cbba862929/.github/ISSUE_TEMPLATE/README.md,1,flowchart,No,No,"Missing accTitle — add it inline after the diagram type (e.g. `    accTitle: My title`); Missing accDescr — add it inline after the diagram type (e.g. `    accDescr: My description`)",⚠️ Non-Compliant


Regenerate the accessibility artefacts from the repo

The regenerated spreadsheet starts with .claude/worktrees/... entries, which are local Claude worktree snapshots rather than files in this commit, so the committed artefacts now report failures for paths consumers cannot fix. This also contradicts the new **/.claude/** ignore and the PR verification claim that Mermaid accessibility passes; please rerun the report/spreadsheet generation after applying that ignore so the published audit reflects only tracked repository files.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-19T07:21:33Z

+  const firstMeaningfulLine = lines.find(
+    (l) => l.trim() !== "" && !l.trim().startsWith("%%"),
+  );
+  if (firstMeaningfulLine && firstMeaningfulLine.trim() === "---") {


Reject pre-type accessibility lines

With the new rule that the first meaningful Mermaid line must be the diagram type, this branch only rejects ---; a block beginning with accTitle: or accDescr: still falls through to the presence-only regex checks and is reported accessible. Existing blocks such as CONTRIBUTING.md already use that pre-type form, so CI can stay green while diagrams violate the new standard; reject any non-comment first line that is not a supported diagram type before checking the attributes.

Useful? React with 👍 / 👎.

…or coercion YAML parses bare hex strings like 8957E5 as scientific notation (895700000) and 007580 as decimal integer (7580), causing label-sync.js to crash with "labelObj.color.replace is not a function". Quote all affected color values in labels.yml and add String() coercion in label-sync.js for defence-in-depth. Also regenerates mermaid accessibility reports now that .claude/** worktree paths are excluded from the glob scan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

ashleyshaw · 2026-06-19T08:48:11Z

@Mergifyio queue

mergify · 2026-06-19T08:48:46Z

github-actions Bot assigned ashleyshaw Jun 19, 2026

github-actions Bot added this to the fix(a11y): ISSUE_TEMPLATE README.md Mermaid diagram missing YAML header block `a milestone Jun 19, 2026

claude added 4 commits June 19, 2026 06:15

gemini-code-assist Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread scripts/validation/validate-mermaid-accessibility.js

Comment thread scripts/validation/validate-mermaid-accessibility.js

ashleyshaw force-pushed the fix/mermaid-inline-accessibility-syntax branch from 549c061 to 443a6c2 Compare June 19, 2026 07:16

ashleyshaw marked this pull request as ready for review June 19, 2026 07:16

coderabbitai Bot requested a review from krugazul June 19, 2026 07:17

chatgpt-codex-connector Bot reviewed Jun 19, 2026

View reviewed changes

github-actions Bot added area:labels Label governance and routing and removed type:documentation Documentation labels Jun 19, 2026

fix(changelog): add label-sync color coercion entry

4b44f89

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuT8NQeGYY9UQHLsX3MMHc

coderabbitai Bot approved these changes Jun 19, 2026

View reviewed changes

ashleyshaw removed the meta:needs-changelog Requires a changelog entry before merge label Jun 19, 2026 — with Claude

github-actions Bot added the meta:needs-changelog Requires a changelog entry before merge label Jun 19, 2026

krugazul approved these changes Jun 19, 2026

View reviewed changes

ashleyshaw mentioned this pull request Jun 19, 2026

Release v0.6.0 — Community Health, Governance Docs, and Meta Agent Foundations #968

Closed

32 tasks

ashleyshaw enabled auto-merge (squash) June 19, 2026 08:48

ashleyshaw merged commit 3c26c24 into develop Jun 19, 2026
33 checks passed

ashleyshaw deleted the fix/mermaid-inline-accessibility-syntax branch June 19, 2026 08:53

Conversation

ashleyshaw commented Jun 19, 2026

Fix Pull Request

Linked issues

Summary

Changes

Impact / Compatibility

Verification

Risk & Rollback

Changelog

Fixed

Checklist (Global DoD / PR)

Uh oh!

coderabbitai Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested labels

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 19, 2026

Metadata governance

Uh oh!

github-actions Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎨 Mermaid Diagram Validation

Uh oh!

github-actions Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Reviewer Summary for PR #995

Recommendations

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

ashleyshaw commented Jun 19, 2026

Uh oh!

mergify Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai Bot commented Jun 19, 2026 •

edited

Loading

github-actions Bot commented Jun 19, 2026 •

edited

Loading

github-actions Bot commented Jun 19, 2026 •

edited

Loading

mergify Bot commented Jun 19, 2026 •

edited

Loading