Common WCAG Errors: A Quick Reference Guide

Essential Code Patterns

<!-- Basic keyboard accessible dropdown -->
<button aria-expanded="false" aria-haspopup="menu">Menu</button>
<ul role="menu" hidden>
    <li role="none"><a href="#" role="menuitem">Option 1</a></li>
</ul>

<!-- Custom interactive element -->
<div tabindex="0" role="slider" 
     aria-valuenow="50" aria-valuemin="0" aria-valuemax="100"
     onkeydown="handleArrowKeys(event)">
</div>

<!-- Skip links (first elements on page) -->
<a href="#main-content" class="skip-link">Skip to main content</a>
<a href="#navigation" class="skip-link">Skip to navigation</a>

Interactive Demos: Keyboard Navigation guide: Tab widget demo, dropdown, skip links and modal focus trapping

Essential Code Patterns

/* Ensure minimum 4.5:1 contrast for normal text */
.link-text {
    color: #0066cc; /* 4.51:1 on white background */
}

/* Large text: 18pt (24px) and larger, or 14pt (18.67px) and larger when bold */
.large-text {
    color: #767676; /* 4.54:1 on white background - meets AA large text */
    font-size: 24px; /* 18pt = 24px minimum for large text */
}

/* Fix subtle button outlines that blend with background */
.button {
    background: #0066cc;
    color: white;
    border: 2px solid #004499; /* Darker border for definition */
}

.button:hover {
    background: #0052a3; /* Darker on hover, still 4.5:1+ contrast */
    border: 2px solid #003366;
}

.button:focus {
    outline: 3px solid #d84a00; /* 4.3:1 on white, meets 3:1 for focus indicators */
    outline-offset: 2px;
}

/* Dark theme considerations */
.dark-theme {
    background: #1a1a1a;
    color: #ffffff; /* 15.3:1 contrast ratio */
}

/* Ensure text over gradients has sufficient contrast */
.gradient-banner {
    background: linear-gradient(135deg, #0066cc, #004499);
    color: white; /* Test against darkest gradient color */
    text-shadow: 1px 1px 2px rgba(0,0,0,0.8); /* Backup for edge cases */
}

Testing Tools

• WebAIM Contrast Checker
• Colour Contrast Analyser
• Browser DevTools accessibility features

Interactive Demos: Color Contrast guide: Interactive contrast checker and accessible color palettes

Essential Code Patterns

<!-- Proper button labeling -->
<button aria-label="Open calendar">
    <svg aria-hidden="true"><!-- calendar icon --></svg>
</button>

<!-- Form labels -->
<label for="username">Username (required)</label>
<input type="text" id="username" name="username" required aria-describedby="username-help">
<div id="username-help">Enter your email address</div>

<!-- iframe accessibility -->
<iframe src="map.html" title="Interactive campus map"></iframe>

<!-- Form with proper error handling -->
<form novalidate>
    <input type="email" 
           id="email" 
           required 
           aria-describedby="email-error"
           aria-invalid="false">
    <div id="email-error" role="alert"></div>
</form>

Interactive Demos: Form Labels guide: Screen reader announcement demo for labels, icon buttons and fieldsets

Essential Code Patterns

<!-- Proper heading hierarchy -->
<h1>Main Page Title</h1>
<h2>Section Title</h2>
<h3>Subsection Title</h3>
<h4>Sub-subsection Title</h4>

<!-- Semantic landmarks -->
<header>
    <nav aria-label="Main navigation">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/about">About</a></li>
        </ul>
    </nav>
</header>

<main>
    <article>
        <h1>Article Title</h1>
        <section>
            <h2>Section Title</h2>
        </section>
    </article>
</main>

<aside aria-label="Related articles">
    <h2>Related Content</h2>
</aside>

<footer>
    <p>&copy; 2025 Company Name</p>
</footer>

Essential Code Patterns

<!-- Skip links should be first focusable elements -->
<a href="#main-content" class="skip-link">Skip to main content</a>
<a href="#navigation" class="skip-link">Skip to navigation</a>

<nav id="navigation" aria-label="Main navigation">
    <!-- Navigation items -->
</nav>

<main id="main-content" tabindex="-1">
    <h1>Main Content Starts Here</h1>
    <!-- Main page content -->
</main>

<!-- Skip links CSS -->
<style>
.skip-link {
    position: absolute;
    top: -40px;
    left: 6px;
    background: #000;
    color: #fff;
    padding: 8px 16px;
    text-decoration: none;
    border-radius: 0 0 4px 4px;
    z-index: 1000;
    transition: top 0.3s ease;
}

.skip-link:focus {
    top: 6px; /* Slide down when focused */
}
</style>

Interactive Demos: Keyboard Navigation guide: Skip links implementation and testing steps

Essential Code Patterns

/* Custom focus indicators */
.button:focus {
    outline: 3px solid #d84a00; /* 4.3:1 on white */
    outline-offset: 2px;
}

/* For elements where outline doesn't work well */
.card:focus {
    box-shadow: 0 0 0 3px #d84a00;
}

/* For dark backgrounds */
.dark-theme .button:focus {
    outline: 3px solid #ffcc00; /* Bright yellow on dark */
    outline-offset: 2px;
}

/* NEVER remove focus indicators entirely */
/* DON'T do this: *:focus { outline: none; } */

Interactive Demos: Color Contrast guide: Focus indicator styling with sufficient contrast

Essential Code Patterns

<!-- Descriptive headings -->
<h1>User Dashboard - Account Overview</h1>
<h2>Recent Transaction History</h2>
<h2>Account Security Settings</h2>

<!-- Descriptive form labels -->
<label for="search-products">Search products by name or category</label>
<input type="search" id="search-products" placeholder="e.g., wireless headphones">

<!-- Group related fields -->
<fieldset>
    <legend>Shipping Address</legend>
    <label for="street">Street Address (required)</label>
    <input type="text" id="street" name="street" required>
    
    <label for="city">City (required)</label>
    <input type="text" id="city" name="city" required>
</fieldset>

Interactive Demos: Form Labels guide: Descriptive label patterns and fieldset grouping

Essential Code Patterns

<!-- Links with multiple indicators -->
<a href="/download" class="download-link">
    Download Report 
    <svg aria-hidden="true"><!-- download icon --></svg>
</a>

<!-- Error messages with icons and text -->
<div class="error-message" role="alert">
    <svg aria-hidden="true"><!-- error icon --></svg>
    <strong>Error:</strong> Email address is required
</div>

<!-- Status indicators with text + icons + color -->
<span class="status-success">
    <svg aria-hidden="true"><!-- checkmark icon --></svg>
    Success
</span>
<span class="status-warning">
    <svg aria-hidden="true"><!-- warning icon --></svg>
    Warning
</span>
<span class="status-error">
    <svg aria-hidden="true"><!-- X icon --></svg>
    Error
</span>

Interactive Demos: Form Validation guide: Errors identified by text and icons, not just color

Essential Code Patterns

<!-- Descriptive link text -->
<!-- BAD: <a href="/report.pdf">Click here</a> -->

<!-- GOOD -->
<a href="/report.pdf">Download accessibility report (PDF, 2.3MB)</a>
<a href="/wcag-guide">Read more about WCAG implementation</a>

<!-- External links with indicators -->
<a href="https://w3.org/WAI" rel="noopener">
    Web Accessibility Initiative
    <span class="sr-only">(opens in new window)</span>
    <svg aria-hidden="true" class="external-icon">
        <!-- external link icon -->
    </svg>
</a>

<!-- Context-specific "read more" links -->
<article>
    <h3>Product Review</h3>
    <p>Our latest smartphone review...</p>
    <a href="/review/smartphone-2025">Read full smartphone review</a>
</article>

Essential Code Patterns

/* Responsive design without horizontal scrolling */
.container {
    max-width: 1200px;
    width: 100%;
    margin: 0 auto;
    padding: 0 20px;
}

/* Flexible layouts */
.grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}

/* Text that scales properly */
body {
    font-size: 1rem; /* Use rem units */
    line-height: 1.5;
}

/* Responsive images */
img {
    max-width: 100%;
    height: auto;
}

/* Avoid fixed widths */
/* BAD: .sidebar { width: 300px; } */

/* Use flexible widths */
.sidebar {
        width: 100%;
    max-width: 300px;
}

Essential Code Patterns

<!-- Use tabindex to control focus order when needed -->
<main id="main-content">
    <h1 tabindex="-1">Page Title</h1> <!-- Can receive focus programmatically -->
    
    <nav aria-label="Page contents">
        <a href="#section1">Section 1</a>
        <a href="#section2">Section 2</a>
    </nav>
    
    <section id="section1" tabindex="-1">
        <h2>Section 1</h2>
        <!-- Content -->
    </section>
</main>

<!-- Modal focus trap JavaScript -->
<script>
function openModal(modalId) {
    const modal = document.getElementById(modalId);
    const focusableElements = modal.querySelectorAll(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    
    const firstElement = focusableElements[0];
    const lastElement = focusableElements[focusableElements.length - 1];
    
    // Focus first element
    firstElement.focus();
    
    // Trap focus within modal
    modal.addEventListener('keydown', function(e) {
        if (e.key === 'Tab') {
            if (e.shiftKey) {
                if (document.activeElement === firstElement) {
                    lastElement.focus();
                    e.preventDefault();
                }
            } else {
                if (document.activeElement === lastElement) {
                    firstElement.focus();
                    e.preventDefault();
                }
            }
        }
    });
}
</script>

Interactive Demos: Keyboard Navigation guide: Tab order management and focus trapping for modals

Essential Code Patterns

<!-- Informative images -->
<img src="chart.png" alt="Sales increased 25% from January to March 2025">

<!-- Decorative images -->
<img src="decoration.png" alt="" role="presentation">

<!-- Complex images with detailed description -->
<img src="process-diagram.png" alt="User registration process" aria-describedby="process-desc">
<div id="process-desc">
    The diagram shows 4 steps: 1) User fills form, 2) Email verification, 
    3) Admin approval, 4) Account activated
</div>

<!-- Icons in buttons -->
<button>
    <svg aria-hidden="true"><!-- save icon --></svg>
    Save Document
</button>

<!-- Icon-only buttons -->
<button aria-label="Close dialog">
    <svg aria-hidden="true"><!-- close icon --></svg>
</button>

Essential Code Patterns

<!-- Correct ARIA landmark structure -->
<header role="banner">
    <nav role="navigation" aria-label="Main navigation">
        <ul>
            <li><a href="#" aria-current="page">Home</a></li>
            <li><a href="#">About</a></li>
        </ul>
    </nav>
</header>

<main role="main">
    <section aria-labelledby="products-heading">
        <h2 id="products-heading">Our Products</h2>
        
        <!-- Expandable content with proper ARIA -->
        <button aria-expanded="false" 
                aria-controls="product-details"
                onclick="toggleDetails()">
            Show Product Details
        </button>
        
        <div id="product-details" aria-hidden="true">
            <p>Detailed product information...</p>
        </div>
    </section>
</main>

<!-- Live regions for dynamic content -->
<div id="status-polite" aria-live="polite" aria-atomic="true" class="sr-only"></div>
<div id="status-assertive" aria-live="assertive" aria-atomic="true" class="sr-only"></div>

Testing ARIA

• Use screen readers (NVDA, JAWS, VoiceOver) to test ARIA announcements
• Browser DevTools accessibility tree to verify ARIA structure
• W3C Using ARIA Guide
• ARIA Authoring Practices Guide

Interactive Demos: Accessible Dropdown Menus guide: Working ARIA menu pattern with state management

Essential Code Patterns

<!-- Form with proper error handling -->
<form novalidate>
    <label for="email">
        Email Address 
        <span class="required" aria-label="required">*</span>
    </label>
    <input type="email" 
           id="email" 
           required 
           aria-describedby="email-error email-help"
           aria-invalid="false">
    <div id="email-help">We'll never share your email</div>
    <div id="email-error" role="alert" aria-live="polite"></div>
    
    <button type="submit" aria-describedby="submit-help">
        <svg aria-hidden="true"><!-- submit icon --></svg>
        Create Account
    </button>
    <div id="submit-help">By clicking, you agree to our terms</div>
</form>

<!-- JavaScript for error handling -->
<script>
function validateEmail(input) {
    const errorDiv = document.getElementById('email-error');
    
    if (!input.validity.valid) {
        input.setAttribute('aria-invalid', 'true');
        errorDiv.textContent = 'Please enter a valid email address';
    } else {
        input.setAttribute('aria-invalid', 'false');
        errorDiv.textContent = '';
    }
}
</script>

Interactive Demos: Form Validation guide: Accessible registration form with real-time validation

Essential Code Patterns

<!-- Set page language -->
<html lang="en">

<!-- Language changes -->
<p>Welcome! <span lang="es">¡Bienvenidos!</span> <span lang="fr">Bienvenue!</span></p>

<!-- Accessible names that match visible text -->
<!-- BAD: Accessible name doesn't include visible text -->
<button aria-label="Submit form">Send Message</button>

<!-- GOOD: Accessible name starts with visible text -->
<button aria-label="Send Message - Submit contact form">Send Message</button>

<!-- Even better: Let visible text be the accessible name -->
<button>Send Message</button>

Interactive Demos: Form Labels guide: Accessible names that match visible text (2.5.3 Label in Name)