Statamic Accessibility Checklist 2026 | WCAG 2.1 AA & EAA Compliance

Last updated: 2026-05-02

Statamic is the flat-file CMS that Laravel agencies and developer-led teams reach for when they need a content editor experience as polished as WordPress's Gutenberg but with the file-based version control story of a static site generator. Sites are built with Antlers or Blade templates, content lives in YAML or markdown files committed to git, and editors interact through a Vue-based control panel that includes the Bard rich-text editor, asset library, and Live Preview pane. That architecture surfaces a particular set of accessibility risks. The Bard editor allows editors to choose any heading level from a dropdown, which often produces pages with multiple H1s or skipped levels. The Asset fieldtype stores alt text in a separate panel that editors frequently overlook because the upload flow does not require it. Antlers and Blade templates inherit whatever accessibility hygiene the developer wrote, with no built-in landmarks or skip links unless the starter kit includes them. With the European Accessibility Act enforceable since 28 June 2025 against any business that sells digital products into the EU, and the United States Department of Justice rule for Title II web accessibility now binding for state and local governments, Laravel agencies building Statamic sites for public-facing clients have a real compliance obligation. This checklist is written for the editor and developer working together: editor-facing tasks they can complete inside the control panel, and template-level fixes the developer can ship in Antlers or Blade. Each issue cites the specific WCAG 2.1 success criterion that applies.

Common Accessibility Issues

critical

Bard Editor Heading Dropdown Allows Any Level With No Hierarchy Validation

WCAG 1.3.1

The Bard rich-text fieldtype exposes a heading dropdown with H1 through H6 options. Editors choose a level based on the visual size they want, not based on document structure, which produces pages where the entry title (already an H1 in the template) is followed by another H1 in the body, or where a section jumps from H2 to H4. Screen-reader users cannot skim the page by heading and landmark relationships break.

How to fix:

In your blueprint configuration (resources/blueprints/collections/pages/page.yaml or similar), restrict the Bard heading levels with the heading_levels option set to ['h2', 'h3', 'h4'] so editors cannot insert an H1 inside body content. Add a heading-hierarchy validation rule using a custom Statamic Action or git pre-commit hook that runs when YAML files are saved. Train editors to think of headings as outline structure, not visual size, and apply CSS to make the visual size match the desired hierarchy.

Before 
buttons:
  - h1
  - h2
  - h3
  - h4
  - bold
  - italic
  - link
After 
buttons:
  - h2
  - h3
  - h4
  - bold
  - italic
  - link
heading_levels:
  - h2
  - h3
  - h4
critical

Asset Library Uploads Skip the Alt Text Field

WCAG 1.1.1

Statamic's asset library lets editors drag and drop images into a folder and reference them from any entry. The asset metadata schema includes an alt field by default, but the upload flow only prompts for it on the first edit, not at upload time. Editors typically batch-upload twenty images for a portfolio and never return to fill in alt text, leaving the rendered img tags with empty or missing alt attributes.

How to fix:

Configure the asset container blueprint (resources/blueprints/assets/{container}.yaml) with alt as a required field and add a validation rule. In Antlers or Blade templates, never reference {{ asset:url }} directly without also outputting {{ asset:alt }}. Add a control-panel listing widget that shows assets missing alt text so editors get a queue to work through. The first-party Statamic Asset Audit add-on by Joel Clermont surfaces this list automatically.

Before 
<img src="{{ url }}" />

# blueprint
fields:
  - handle: alt
    field:
      type: text
After 
<img src="{{ url }}" alt="{{ alt }}" />

# blueprint
fields:
  - handle: alt
    field:
      type: text
      validate:
        - required
        - max:200
      instructions: 'Describe what the image conveys in context. Leave blank only if the image is purely decorative.'
serious

Antlers Templates Lack Landmark Roles and Skip Links

WCAG 2.4.1

Most Statamic starter kits including the official Cool Writings, Starter, and Peak kits ship with Antlers layouts that wrap content in generic div containers without nav, main, or footer landmarks. Skip links are not included by default. Keyboard users have to tab through every header link before reaching the main content on every page load.

How to fix:

Edit resources/views/layout.antlers.html and replace top-level divs with semantic landmarks: <header>, <nav aria-label='Primary'>, <main id='main-content'>, <aside>, and <footer>. Add a skip link as the first focusable element inside <body>: <a class='skip-link' href='#main-content'>Skip to main content</a>. Style the link to be visually-hidden until focused with the standard sr-only-focusable utility. Verify in a browser by pressing Tab from the URL bar and confirming the skip link appears.

Before 
<body>
  <div class="header">
    <div class="nav">{{ partial:nav }}</div>
  </div>
  <div class="content">
    {{ template_content }}
  </div>
  <div class="footer">{{ partial:footer }}</div>
</body>
After 
<body>
  <a class="skip-link" href="#main-content">Skip to main content</a>
  <header>
    <nav aria-label="Primary">{{ partial:nav }}</nav>
  </header>
  <main id="main-content">
    {{ template_content }}
  </main>
  <footer>{{ partial:footer }}</footer>
</body>
serious

Statamic Forms Render Without Programmatic Label Association

WCAG 3.3.2

The Statamic Forms addon generates form markup by iterating over field handles, and the default {{ form:create }} loop wraps inputs in div containers without label-for-id pairing. The placeholder attribute often substitutes for the label. Screen-reader users do not get programmatic field names, and users with cognitive disabilities lose the prompt as soon as they start typing.

How to fix:

Override the default form template by publishing the addon views with php artisan vendor:publish --tag=statamic-forms-views. Edit resources/views/vendor/statamic/forms/fields.antlers.html and change the wrapping markup to use <label for='{{ handle }}'> with a matching id='{{ handle }}' on the input. Add aria-describedby pointing to inline help text and aria-invalid='true' on fields that failed validation. The Statamic 5 documentation on form theming gives full examples.

Before 
<div class="field">
  <input type="{{ input_type }}" name="{{ handle }}" placeholder="{{ display }}" value="{{ value }}" />
</div>
After 
<div class="field">
  <label for="field-{{ handle }}">{{ display }}{{ if validate | contains:required }}<span aria-hidden="true">*</span><span class="sr-only"> (required)</span>{{ /if }}</label>
  <input id="field-{{ handle }}" type="{{ input_type }}" name="{{ handle }}" value="{{ value }}" {{ if validate | contains:required }}aria-required="true" required{{ /if }} {{ if errors:has }}aria-invalid="true" aria-describedby="error-{{ handle }}"{{ /if }} />
  {{ if errors:has }}<p id="error-{{ handle }}" class="error">{{ errors:first }}</p>{{ /if }}
</div>
moderate

Live Preview Iframe Has No Title When Embedded in Editor

WCAG 4.1.2

Statamic's Live Preview feature shows an iframe with the rendered front-end inside the control panel as editors type. The iframe has no title attribute, which means editors using a screen reader receive only 'frame' with no description. While the control panel is internal, public-facing freelancer and consultant Statamic sites often include client logins to the control panel itself, so editor accessibility matters for compliance.

How to fix:

Override the control-panel view that renders Live Preview by publishing the cp views and editing resources/views/vendor/statamic/cp/livepreview.antlers.html. Add title='Live preview of {{ title }}' to the iframe. If you maintain a multi-tenant Statamic Pro install, update the addon configuration to inject the iframe title automatically based on the entry title. Long-term, watch the Statamic GitHub issue tracker for upstream fixes and contribute the patch back if your version is current.

moderate

Color-Only Status Indicators on Entry Listings

WCAG 1.4.1

The Statamic control panel and many starter-kit front-ends use color alone to communicate entry status: a green dot for published, an orange dot for scheduled, a red dot for unpublished. Users with red-green color blindness cannot distinguish published from unpublished, and screen-reader users hear nothing at all because the color is communicated via CSS background only.

How to fix:

On the front-end, pair every color status with a text label or icon shape. Edit your entry listing partial and replace <span class='status status--published'></span> with <span class='status status--published'><span class='sr-only'>Published</span></span>, optionally adding a checkmark icon for additional redundancy. In the control panel, the Statamic team has shipped accessible status badges since version 5.4, so upgrade if you are on an older release.

Statamic-Specific Tips

  • Statamic's blueprint system is your primary leverage point. A single blueprint change cascades to every entry that uses it, so adding alt-text validation or restricting Bard heading levels in the blueprint instantly enforces the rule across hundreds of pages.
  • When using the Bard fieldtype with sets (custom block components), audit each set's Antlers partial individually. Sets are essentially mini-templates and inherit no parent accessibility constraints. Common sets like image-gallery, video-embed, and call-to-action need explicit alt text, captions, and accessible names respectively.
  • Statamic Pro supports user roles and permissions. Create a 'Content Editor' role that can publish only after a separate 'Accessibility Reviewer' role approves the draft. The Statamic Workflow add-on by Goldnet provides the gating logic.
  • Run php artisan statamic:assets:meta after migrating an asset library to ensure all assets have metadata records. Then write a one-off script to flag assets where alt is null or empty and surface them in a control-panel listing widget for editors to fix.
  • Statamic 5 introduced first-party support for Tailwind 4. If you are scaffolding a new site, use the Peak starter kit which ships with focus-visible utilities and accessible default colors that pass 4.5:1 contrast out of the box. For older Tailwind 3 projects, add @tailwindcss/forms to fix default form-element rendering issues.

axe DevTools

Browser extension that scans Statamic-rendered front ends for WCAG violations including missing alt text, contrast failures, and missing landmarks. Pair with Statamic's git-versioned content for repeatable audits.

Statamic Asset Audit add-on

Control-panel widget that lists assets missing alt text or other required metadata, providing editors a queue of items to fix without leaving the Statamic dashboard.

pa11y-ci

Command-line accessibility tester that runs WCAG checks against a list of URLs. Wire to your deploy pipeline alongside Statamic's static caching to test every published entry on every deploy.

Further Reading

Other CMS Checklists