Statamic A11Y Gate Laravel Package

Getting Started

This is a Statamic addon that checks an entry's rendered page for accessibility problems and refuses the save when it finds them. Findings are pointers into your own page content — a duplicate heading's text, an image's src, a link's words — so the workflow is "write, press Check, fix what it names, publish".

Minimal steps:

1. composer require the addon (the README's new ## Installing section has the exact line), on the Statamic and PHP floors it states. Install ext-intl if you want what the README says it adds.
2. Publish config and assets: php artisan statamic:install, or php artisan vendor:publish --tag=statamic-a11y-gate --force if you only want this addon's files. Read the published config first — that is where you decide which collections are gated.
3. Open an entry in the control panel. The auto-placed Accessibility panel is where you press Check; findings render there with the offending content quoted.
4. The Tools page in the CP is the site-wide surface — lists of what it found, plus the render-failure messages when a page could not be fetched.

First real use case: take one existing entry that you know has problems, press Check, and read the findings against the page. That tells you faster than the docs whether the gate is scoped correctly for your site.

Implementation Patterns

Check before Save & Publish, not after. The gate hooks the save pipeline, so a refused save is the normal failure mode. Treat a refusal as a normal authoring step: the panel opens with the findings listed, the author fixes the named elements, saves again. On viewports where Statamic folds the sidebar into a tab (tablets, small laptops) the panel now asks Statamic's own reveal to switch to the offending tab and scroll it into view — so the "The given data was invalid" toast is a pointer to the panel, not the whole message. That reveal call is guarded, so a Statamic build without it falls back to drawing the alert in place.

Scope the gate deliberately. The panel is auto-placed on gated collections; keep the gate on the collections that are public-facing and content-heavy, and leave it off internal/utility collections where a refusal is just friction. For collections outside the automatic placement, add the field to the blueprint by hand. The field stores nothing — it is a UI surface only, so do not build queries, exports, or filters against its value.

Findings are untrusted display data, always. As of 0.10.2 every string the panel draws goes through Vue's escaping, page-derived or not. If you write your own panel components, or a custom report view, that renders findings, use {{ }} / v-text — never v-html. The heading that broke this was <img src=/x.png onerror=...> written into page content: escaped and harmless on the front end, decoded and executed in the CP of whoever pressed Check. Assume anyone who can write into a gated entry can put anything in a finding.

Pair it with a real audit for the gaps. The Tools page now says "Anything it finds" rather than "Anything that would fail WCAG 2.2 AA stops the publish" — that is the honest reading. Colour contrast is explicitly not checked. Use the addon as a publish-time tripwire for structural problems, and keep an actual audit (manual or an external scanner) for conformance claims. Do not let a stakeholder read the gate as a compliance guarantee.

Asset publishing is part of your deploy. The panel is Vue components shipped as published assets. If your deploy does not run vendor:publish, the fix in 0.10.2 never reaches the browser. Wire php artisan vendor:publish --tag=statamic-a11y-gate --force into the deploy (or statamic:install) and confirm the published files change when the package version does.

Gotchas and Tips

• Upgrade to 0.10.2 and republish assets. 0.10.1 and earlier draw page-derived strings through innerHTML, so an author on a gated entry can plant script that runs in an admin's control panel. Upgrading composer.json alone is not enough — the compiled JS in your public/ tree must be refreshed. This was confirmed on a live CP, not reasoned from the code.
• --tag=laravel-assets is wrong. The 0.8.0 release note told you to use it, and it publishes nothing for this addon. The correct tag is statamic-a11y-gate. Any blog post, bookmark, or internal runbook copied from that note is still wrong.
• Class names in the CP are not guaranteed to exist. The control panel's compiled stylesheet is Tailwind-purged; the addon wrote list-disc, it was silently dropped, and lists drew flat for several releases. 0.10.2 now uses an inline style and ships a test that reads the build and checks every class the addon writes against it. If you extend the panel with your own markup, do not assume a utility class is present — check the built stylesheet, or use inline styles for anything structural.
• Two message strings changed. Render-failure messages no longer end in .. (Laravel's own message supplies the full stop, and each quote was adding another), and the Tools page copy changed to "Anything it finds". If you assert on those strings in tests or screenshot them in docs, update both.
• Don't expect a listings column. The auto-placed Accessibility panel is listable: false as of 0.10.2 — the field stores nothing, so the column could only ever be empty. If someone asks for "accessibility status at a glance in the entries list", that is a custom build, not a config toggle.
• Render failures are a different class of problem from findings. A finding means the page rendered and something is wrong with it; a render failure means the checker could not read the page at all (unreachable, erroring, timed out). Debug those as an infrastructure issue — check the URL the entry resolves to, not the entry's content.
• The uninstall is not perfectly clean. The README now names the two files an uninstall can leave behind; delete them by hand if you are ripping the addon out.
• Support is one person on a public tracker, no response-time promise. The composer.json support key and the README's ## Support section point at the same place. Plan for that if you are putting this in front of a large authoring team — the answers are in the tracker and the README, not in a private channel.
• Extension points to know: the published config (gate scope), the blueprint field (placement), and the CP Vue components (if you fork the panel's presentation). Statamic's own reveal/save pipeline is the integration seam the addon leans on for the tab-switching behaviour — if you override that pipeline in your own build, verify the refused-save reveal still lands the author on the right tab.