Building Accessible Websites with Craft CMS 5: A Complete Guide to WCAG 2.2 Compliance

Why Web Accessibility Matters for Craft CMS Developers Now More Than Ever

Accessibility lawsuits increased 320% between 2013 and 2018, and the trend continues. Beyond legal compliance, accessible websites reach wider audiences, perform better in search engines, and provide better user experiences for everyone.

The new WCAG 2.2 accessibility standards address real-world issues like mobile accessibility and cognitive load. Key WCAG 2.2 compliance additions include:

• Focus visibility: Users must see where they are on the page
• Target sizes: Touch targets need to be at least 24x24 pixels
• Drag alternatives: Every drag-and-drop action needs a simple alternative
• Consistent help: Help options must appear in the same place across pages

What Craft CMS 5 Accessibility Features Get Right (and Wrong)

Craft CMS 5 ships with significant accessibility improvements for content management systems. The control panel supports screen readers, keyboard navigation, and high contrast modes. You can configure custom fields to enforce accessible content entry, and the system follows semantic HTML patterns.

But Craft CMS isn't perfect for WCAG 2.2 compliance. Some control panel features remain inaccessible, alt text isn't required by default, and the system won't catch all accessibility issues automatically. Third-party plugins vary wildly in their accessibility support.

The key insight: Craft CMS gives you the tools for building accessible websites, but you need to configure them correctly.

Setting Up Craft CMS for Accessible Content Creation and WCAG Compliance

Your accessibility journey starts in the Craft CMS control panel. Here's how to configure fields that guide authors toward accessible content creation:

Make Alt Text Required for Image Accessibility

In your Asset field settings, enable the "Alternative Text" field and mark it as required. This prevents authors from uploading images without descriptions for screen reader users.

Go further by adding helpful instructions: "Describe what's shown in the image for someone who can't see it. If it's decorative, write 'decorative image'."

Enforce Heading Hierarchy with Matrix Fields for Better Screen Reader Navigation

Free-form rich text editors let authors create heading chaos—H2 followed by H5, or worse, fake headings using bold text. Matrix fields solve this accessibility problem:

Create a "Heading" block with:

• A dropdown limited to H2, H3, H4 options
• A text field for the heading content
• Clear instructions about when to use each level

This forces proper heading structure while keeping content flexible for content creators.

Limit Rich Text Options for Accessible Content Creation

Configure your rich text fields to only include accessible formatting options:

• Headings (H2-H4 only)
• Bold and italic
• Lists (bulleted and numbered)
• Links

Remove color options, font size controls, and other formatting that can create accessibility barriers for users with disabilities.

Building Accessible Frontend Templates with Semantic HTML

Your Twig templates need to output semantic, keyboard-navigable HTML for WCAG 2.2 compliance. Here are the essential patterns:

Use Semantic HTML Structure for Screen Reader Compatibility

<header>
  <nav aria-label="Main navigation">
    <!-- navigation content -->
  </nav>
</header>

<main id="main-content">
  <article>
    <header>
      <h1>{{ entry.title }}</h1>
    </header>
    <!-- article content -->
  </article>
</main>

<footer>
  <!-- footer content -->
</footer>

Handle Images Properly for WCAG 2.2 Image Accessibility

{% if entry.featuredImage|length %}
  {% set image = entry.featuredImage.one() %}
  <img src="{{ image.url }}" 
       alt="{{ image.alt ? image.alt : 'Featured image for ' ~ entry.title }}"
       width="{{ image.width }}" 
       height="{{ image.height }}">
{% endif %}

Always provide fallback alt text, but encourage authors to write their own through field instructions for better accessibility compliance.

Create Accessible Forms for Better User Experience

<form method="post">
  {{ csrfInput() }}
  
  <div class="form-group">
    <label for="email">Email Address</label>
    <input type="email" 
           id="email" 
           name="email" 
           required 
           aria-describedby="email-help">
    <div id="email-help">We'll never share your email address.</div>
  </div>
  
  <button type="submit">Subscribe to Newsletter</button>
</form>

Add Skip Links for Keyboard Navigation Accessibility

<a href="#main-content" class="skip-link">Skip to main content</a>

Style skip links to appear on focus for keyboard users:

.skip-link {
  position: absolute;
  top: -40px;
  left: 6px;
  background: #000;
  color: #fff;
  padding: 8px;
  text-decoration: none;
  z-index: 1000;
}

.skip-link:focus {
  top: 6px;
}

Ensure Visible Focus Styles for WCAG 2.2 Focus Visibility

button:focus,
a:focus,
input:focus,
textarea:focus,
select:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

Never remove focus styles without providing better alternatives for keyboard navigation accessibility.

Essential Testing Strategies for WCAG 2.2 Compliance

Automated tools catch about 30% of accessibility issues. You need both automated and manual testing for comprehensive WCAG compliance:

Automated Accessibility Testing Tools

Install the axe DevTools browser extension and run it on every page. Look for:

• Missing alt text on images
• Color contrast failures
• Form labeling issues
• Heading hierarchy problems

Manual Testing for Real-World Accessibility

Keyboard navigation testing: Tab through your entire site. Can you reach everything? Is the focus order logical for screen reader users?

Screen reader testing: Try NVDA (Windows) or VoiceOver (Mac). Do page sections make sense when read aloud?

Zoom testing: Increase browser zoom to 200%. Does content remain usable for users with visual impairments?

Color vision testing: Use browser extensions to simulate color blindness. Is information still clear without color cues?

Content Quality Checks for Accessible Content Creation

Train your authors to:

• Write descriptive alt text ("Woman presenting quarterly sales data to team" not "Woman at computer")
• Use meaningful link text ("Download Q3 sales report" not "Click here")
• Structure content with proper headings for screen reader navigation
• Avoid directional instructions ("Click the blue button on the right")

Helpful Craft CMS Plugins and Tools for Web Accessibility

Several Craft CMS plugins can boost your accessibility efforts for WCAG 2.2 compliance:

All in One Accessibility Plugin for Craft CMS

This plugin adds a customizable accessibility toolbar with features like:

• Screen reader optimization
• Text magnification for users with visual impairments
• Color adjustments for various vision types
• Keyboard navigation aids
• Support for 140 languages

Install it via the Plugin Store and customize the toolbar to match your site's accessibility needs.

Imager X for Advanced Image Accessibility

Advanced image handling with better alt text management and responsive image support. Particularly useful for complex image workflows in accessible websites.

Accessibility Testing Tools for WCAG Compliance

• axe DevTools: Browser extension for automated accessibility testing
• WAVE: Web accessibility evaluation tool
• Pa11y: Command-line accessibility testing tool you can integrate into build processes

Common Accessibility Problems and Quick Fixes for Craft CMS Sites

Missing alt text on images: Make asset alt text fields required and provide clear instructions about writing descriptions for screen readers.

Poor heading structure: Use Matrix fields instead of rich text for headings. Limit heading options to H2-H4 for proper hierarchy.

Low color contrast ratios: Test all color combinations with WebAIM's contrast checker. Aim for 4.5:1 ratio for normal text in WCAG 2.2 compliance.

Inaccessible third-party plugins: Always test third-party plugins with screen readers and keyboard navigation before going live.

Focus traps in interactive elements: Ensure users can Tab out of all interactive elements. Modal dialogs need special focus management for accessibility.

Training Your Content Team for Accessible Content Creation

Your website's accessibility depends heavily on content authors understanding WCAG guidelines. Create simple guidelines:

• Alt text writing: Describe the image's content and context, not its visual characteristics
• Link text best practices: Make links descriptive enough to understand out of context
• Heading usage for screen readers: Use headings for structure, not styling
• Document structure: Start with H1, then H2, then H3—no skipping levels

Provide examples of good and bad practices for accessible content creation. Regular training sessions work better than lengthy documentation.

Testing Your Craft CMS Accessibility Setup for WCAG 2.2

Here's a quick checklist to verify your Craft CMS accessibility setup meets WCAG 2.2 standards:

• Alt text fields are required for all images
• Heading hierarchy is enforced through field configuration
• Rich text options are limited to accessible formatting
• Templates use semantic HTML elements
• Focus styles are visible and consistent
• Forms have proper labels and error handling
• Skip links are present and functional
• Color contrast meets WCAG 2.2 AA standards
• All interactive elements work with keyboard navigation
• Content guidelines are documented and shared

Moving Forward with Accessible Craft CMS Development

Building accessible websites with Craft CMS 5 requires upfront planning and ongoing attention to WCAG 2.2 compliance. The platform provides excellent tools for creating author-friendly, compliant websites—but only if you configure them thoughtfully.

Start with your content structure for accessible content management. Use Matrix fields and custom field types to guide authors toward accessible content creation. Build semantic templates that work well with assistive technologies. Test regularly with both automated tools and real users.

Remember: accessibility is a process, not a project. As your content grows and your site evolves, keep testing and refining your approach to maintain WCAG compliance.

Your next steps for building accessible Craft CMS websites:

• Audit your current Craft CMS setup against WCAG 2.2 requirements
• Configure fields to enforce accessibility best practices
• Update templates to use semantic HTML patterns
• Train your content team on accessibility guidelines
• Establish regular testing routines for ongoing compliance

The investment pays off through reduced legal risk, broader audience reach, and websites that work better for everyone including users with disabilities.