Guardrail Blocks
Most accessibility failures on WordPress sites are authoring failures: a brand color that doesn’t meet WCAG contrast, a heading hierarchy scrambled by reordering, an accordion built from divs with no keyboard support. They look fine in the editor and fail the audit later.
Guardrail Blocks takes a different approach: instead of offering accessible options, its blocks make the failure impossible to author — and re-verify everything on every page view.
The guarantees
- WCAG-safe color contrast — Button backgrounds come only from your theme’s palette, and the most readable text color is chosen automatically (the live ratio is shown in the sidebar, e.g. «Contrast 8.36:1 — AA ✓»). The pairing is re-validated server-side on every page view against your theme’s current palette, so switching themes or changing brand colors can never leave a failing button behind.
- Unbreakable heading hierarchy — There is no heading level control anywhere. An Accessible Heading derives its level (H2–H6) from how Accessible Sections are nested, and re-derives it when you reorder, nest, or un-nest — the document outline stays valid by construction. Card titles and accordion headers participate too, always one level below their section’s heading.
- Correct interactive semantics — The Accordion ships the full WAI-ARIA disclosure pattern: real buttons inside correctly-leveled headings,
aria-expanded/aria-controlswiring, Enter/Space toggling, arrow-key navigation between headers, and content that stays reachable without JavaScript. - Performance-correct media — The Media Figure renders through core’s responsive-image pipeline with explicit dimensions (no layout shift),
srcset/sizes, a hero toggle forfetchpriority="high"(better LCP) vs. lazy loading, and alt text enforcement with editor warnings.
The blocks
Accessible Section, Accessible Heading, Accessible Button, Card + Card Grid, Accessible Accordion, Notice (info/success/warning/error with correct ARIA roles), Media Figure, and a Table of Contents that is generated from the page’s real outline on every view — it can never go stale.
Safety nets
- The Outline Checker panel (in the page sidebar) watches the whole document — including core Heading blocks — and flags skipped levels and extra H1s with one-click block selection.
- Everything inherits your theme’s colors, spacing, and typography via
theme.json. Nothing fights your design. - The plugin makes zero external requests and collects no data.
Source code & development
The compiled block scripts in build/ are generated with @wordpress/scripts (webpack). The complete, human-readable source code is included with this plugin in the src/ directory (TypeScript and SCSS, one folder per block). To rebuild build/ from it: npm install && npm run build (Node 22; package.json and tsconfig.json are included).
Development happens publicly at https://github.com/breonwilliams/guardrail-blocks, which also carries the full test suite (Jest, PHPUnit, Playwright) and CI.