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-controls wiring, 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 for fetchpriority="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.