Improving Accessibility on Your Drupal Site with the Drupal Accessibility Module

The biggest accessibility improvements happen when you build checking and fixing into your regular content workflow, rather than treating it as a separate project that happens once a year.

Prerequisites

Before you start improving your site's accessibility, make sure you have:

• Administrative access to your Drupal site
• Composer installed for module management (or access to the module installation interface)
• Basic understanding of Drupal module installation and configuration
• Content editor permissions to test real-time feedback features

You'll also want to understand these key accessibility concepts:

WCAG Compliance Levels:

• A: Basic accessibility features
• AA: Standard compliance level (most legal requirements)
• AAA: Highest level (often impractical for most sites)

Common Accessibility Issues:

• Missing alt text for images
• Poor color contrast ratios
• Improper heading structure
• Forms without proper labels
• Non-keyboard accessible navigation

Step-by-Step Implementation Guide

Step 1: Install Essential Accessibility Modules

Start with these three core modules that cover different aspects of accessibility checking:

# Install via Composer (recommended)
composer require drupal/editoria11y
composer require drupal/auto_alter  
composer require drupal/axe

# Enable the modules
drush en editoria11y auto_alter axe -y

If you prefer using the admin interface:

• Go to Extend in your admin menu
• Click Install new module
• Upload or install each module individually
• Check the boxes next to installed modules and click Install

Step 2: Configure Editoria11y for Real-Time Content Checking

Editoria11y provides immediate feedback while content creators work. Here's how to set it up properly:

• Navigate to Configuration > Content authoring > Editoria11y settings
• Check Enable Editoria11y on content forms
• Under Content types, select which content types should be checked (start with Article and Basic Page)
• In Check for issues, enable:
  • Missing alt text
  • Empty headings
  • Very long alt text
  • Suspicious link text
  • Color contrast issues

Configuration Example:

# editoria11y.settings.yml
enable_on_forms: true
content_types:
  - article
  - page
  - blog_post
checks:
  alt: true
  headings: true
  links: true
  contrast: true
  lang: true

Step 3: Set Up Automatic Alt Text Generation

The auto_alter module uses AI to generate alt text for images that don't have any:

• Go to Configuration > Media > Automatic Alternative Text
• Choose your service provider (Microsoft Azure Cognitive Services is most common)
• Enter your API credentials
• Configure which image fields should get automatic alt text
• Set up fallback behavior for when the service is unavailable

API Setup Code Example:

// In your settings.php or settings.local.php
$config['auto_alter.settings']['api_key'] = 'your-azure-api-key';
$config['auto_alter.settings']['api_endpoint'] = 'your-azure-endpoint';
$config['auto_alter.settings']['confidence_threshold'] = 0.7;

Step 4: Configure AXE for Automated Testing

AXE integration provides detailed accessibility reports:

• Visit Reports > Accessibility > AXE Reports
• Click Run AXE scan on your homepage
• Review the results and note issues by priority level
• Set up automated scanning by going to Configuration > System > Cron
• Configure AXE to run scans during off-peak hours

Step 5: Test Your Configuration

After setup, verify everything works:

• Create test content with accessibility issues (image without alt text, poor heading structure)
• Check Editoria11y feedback appears in real-time as you edit
• Upload an image without alt text and confirm auto_alter generates one
• Run an AXE scan and review the detailed report
• Test with keyboard navigation to ensure interactive elements work properly

Code Examples and Implementation Details

Custom Accessibility Checker Integration

If you want to add custom accessibility rules, you can extend the existing modules:

getElementsByTagName('video');
  foreach ($videos as $video) {
    $tracks = $video->getElementsByTagName('track');
    if ($tracks->length === 0) {
      $results[] = [
        'rule' => 'custom-video-captions',
        'message' => 'Video elements should include caption tracks for accessibility.',
        'type' => 'error',
        'element' => $video,
      ];
    }
  }
}

Accessibility Toolbar Implementation

Add a user-facing accessibility toolbar:

// accessibility-toolbar.js
(function ($, Drupal) {
  'use strict';

  Drupal.behaviors.accessibilityToolbar = {
    attach: function (context, settings) {
      // Add font size controls
      $('.font-size-increase', context).click(function() {
        $('body').addClass('large-text');
      });
      
      $('.font-size-decrease', context).click(function() {
        $('body').removeClass('large-text');
      });
      
      // Add high contrast toggle
      $('.high-contrast-toggle', context).click(function() {
        $('body').toggleClass('high-contrast');
      });
    }
  };
})(jQuery, Drupal);
Common Mistakes to Avoid

Mistake 1: Only Running Scans After Launch

Don't wait until your site is complete to check accessibility. Build these checks into your development and content creation process from day one.Mistake 2: Relying Only on Automated ToolsAutomated scanners catch many issues but miss others. Always test with actual screen readers and keyboard navigation.Mistake 3: Generic Alt TextAuto-generated alt text like "image of person" isn't helpful. Review and customize automatically generated descriptions to provide meaningful context.Mistake 4: Ignoring Content Creator TrainingThe best accessibility modules won't help if content creators don't understand why they're important. Provide training on writing good alt text, proper heading structure, and accessible link text.Mistake 5: Fixing Issues Without Understanding ContextAn accessibility scanner might flag a decorative image for missing alt text, but the correct fix is adding alt="" (empty alt attribute), not descriptive text.
Testing and Verification Steps
Manual Testing Checklist
After configuring your accessibility modules, test these scenarios:1. Keyboard Navigation Test:
Tab through all interactive elements
Ensure focus indicators are visible
Verify all functionality works without a mouse2. Screen Reader Test:
Use NVDA (Windows) or VoiceOver (Mac)
Navigate by headings, links, and landmarks
Confirm all content is announced properly3. Color Contrast Verification:
Check text against background colors
Test with high contrast mode enabled
Verify information isn't conveyed by color alone
Automated Verification
Set up regular monitoring:
# Create a simple script to run regular AXE scans
#!/bin/bash
drush axe:scan --url=https://yoursite.com
drush axe:scan --url=https://yoursite.com/contact
drush axe:scan --url=https://yoursite.com/blog
We've found that teams get the best results when they run quick accessibility checks on every piece of content before publishing, rather than doing large audits quarterly.
Advanced Configuration Options
Custom Editoria11y Rules
Create site-specific accessibility rules:
// Add to your theme's JavaScript
ed11y.options.customTests = {
  checkCustomElements: function(element) {
    // Custom logic for your specific components
    const customComponents = element.querySelectorAll('.custom-component');
    customComponents.forEach(component => {
      if (!component.getAttribute('aria-label')) {
        ed11y.results.push({
          element: component,
          test: 'custom-component-label',
          type: 'error',
          message: 'Custom components must have aria-label attributes'
        });
      }
    });
  }
};
Integration with Content Workflows
Connect accessibility checking to your publishing workflow:
checkContent($node);
  
  if (!empty($results['errors'])) {
    // Store errors for editor review
    $node->set('field_accessibility_issues', $results['errors']);
  }
}
Measuring Success
Track your accessibility improvements with these metrics:Automated Metrics:
Number of AXE violations (trend downward)
Percentage of images with alt text
Average color contrast ratios
Heading structure compliance rateUser Experience Metrics:
Task completion rates for keyboard users
Screen reader user feedback
Support tickets related to accessibility issuesBusiness Metrics:
Legal compliance status
Broader audience engagement
SEO improvements from better semantic structure
Conclusion
Setting up accessibility modules in Drupal creates a foundation for inclusive web experiences, but the real improvements come from building accessibility awareness into your daily content and development processes. The combination of real-time feedback through Editoria11y, automated assistance from modules like auto_alter, and regular professional scans with AXE gives you multiple layers of protection against accessibility barriers.We recommend starting with these core modules and gradually expanding your accessibility toolkit based on your site's specific needs and user feedback. Remember that accessibility is an ongoing practice, not a one-time project.If you're planning to improve accessibility across multiple Drupal sites or need help implementing these tools within your team's existing workflow, we can help you develop a systematic approach that builds accessibility checking into your content creation and development processes from the ground up.